151 lines
4.1 KiB
Markdown
151 lines
4.1 KiB
Markdown
---
|
|
title: "Gitee CLI 使用指南"
|
|
description: "码云命令行工具，对标 GitHub CLI，四队共用"
|
|
author: 小橘 🍊
|
|
date: 2026-04-01
|
|
---
|
|
|
|
# Gitee CLI 使用指南
|
|
|
|
码云（Gitee）命令行工具，对标 GitHub CLI (`gh`)，让 agent 和人类都能在终端里管理 Gitee 仓库。
|
|
|
|
**仓库**: [shazhou-ww/gitee-cli](https://github.com/shazhou-ww/gitee-cli)
|
|
|
|
## 安装
|
|
|
|
```bash
|
|
git clone https://github.com/shazhou-ww/gitee-cli.git
|
|
cd gitee-cli && npm install && npm run build
|
|
npm link # 全局可用
|
|
```
|
|
|
|
## 认证
|
|
|
|
### 方式一：环境变量（推荐给 agent）
|
|
|
|
```bash
|
|
export GITEE_TOKEN="your-personal-access-token"
|
|
```
|
|
|
|
### 方式二：交互式登录
|
|
|
|
```bash
|
|
gitee auth login
|
|
```
|
|
|
|
Token 缓存到 `~/.config/gitee-cli/config.json`。
|
|
|
|
### 获取 Token
|
|
|
|
1. 打开 [Gitee Personal Access Tokens](https://gitee.com/profile/personal_access_tokens)
|
|
2. 创建 token，勾选 `projects`、`pull_requests`、`issues`、`notes`
|
|
3. 复制 token
|
|
|
|
### 验证
|
|
|
|
```bash
|
|
gitee auth status
|
|
# ✓ Authenticated as ww-shazhou (Wei Wei)
|
|
```
|
|
|
|
## 命令速查
|
|
|
|
### 仓库
|
|
|
|
```bash
|
|
gitee repo list # 列出所有仓库
|
|
gitee repo view mitsein/mitsein # 查看仓库详情
|
|
gitee repo create my-project # 创建仓库
|
|
gitee repo create my-project --private # 创建私有仓库
|
|
gitee repo clone mitsein/mitsein # clone 仓库
|
|
gitee repo delete owner/repo # 删除仓库（需确认）
|
|
```
|
|
|
|
### Issue
|
|
|
|
```bash
|
|
gitee issue list --repo mitsein/mitsein # 列出 issues
|
|
gitee issue list --repo mitsein/mitsein --state closed # 已关闭的
|
|
gitee issue create --repo mitsein/mitsein --title "Bug" # 创建 issue
|
|
gitee issue view IHWYFN --repo mitsein/mitsein # 查看详情
|
|
gitee issue close IHWYFN --repo mitsein/mitsein # 关闭 issue
|
|
gitee issue comment IHWYFN --repo mitsein/mitsein --body "已修复" # 评论
|
|
```
|
|
|
|
!!! note "Gitee Issue 编号"
|
|
Gitee 的 issue 编号是字母+数字格式（如 `IHWYFN`），不是纯数字。
|
|
|
|
### Pull Request
|
|
|
|
```bash
|
|
gitee pr list --repo mitsein/mitsein # 列出 PR
|
|
gitee pr create --repo mitsein/mitsein --title "feat: xxx" --head feature-branch
|
|
gitee pr view 1 --repo mitsein/mitsein # 查看详情
|
|
gitee pr merge 1 --repo mitsein/mitsein # 合并
|
|
gitee pr close 1 --repo mitsein/mitsein # 关闭
|
|
```
|
|
|
|
### Release
|
|
|
|
```bash
|
|
gitee release list --repo mitsein/mitsein
|
|
gitee release create --repo mitsein/mitsein --tag v1.0.0 --name "v1.0.0"
|
|
```
|
|
|
|
### 组织
|
|
|
|
```bash
|
|
gitee org list
|
|
```
|
|
|
|
### 裸 API 调用（兜底）
|
|
|
|
```bash
|
|
gitee api GET /v5/user # 获取当前用户
|
|
gitee api GET /v5/emojis # 不需要认证的 API
|
|
gitee api POST /v5/repos/owner/repo/issues --field title="Bug"
|
|
```
|
|
|
|
## 常用选项
|
|
|
|
| 选项 | 说明 |
|
|
|---|---|
|
|
| `--json` | 输出原始 JSON（方便 agent 解析） |
|
|
| `--page <n>` | 分页页码 |
|
|
| `--per-page <n>` | 每页条数（默认 20） |
|
|
| `--repo <owner/repo>` | 指定仓库（在 gitee 仓库目录内可省略，自动检测） |
|
|
|
|
## 自动检测仓库
|
|
|
|
在 Gitee 仓库目录内执行命令时，`--repo` 可以省略：
|
|
|
|
```bash
|
|
cd ~/mitsein # 这是一个 gitee.com 的 git 仓库
|
|
gitee issue list # 自动检测为 mitsein/mitsein
|
|
```
|
|
|
|
支持 HTTPS 和 SSH 两种 remote 格式。
|
|
|
|
## 环境变量
|
|
|
|
| 变量 | 说明 |
|
|
|---|---|
|
|
| `GITEE_TOKEN` | Personal Access Token（优先级高于 config 文件） |
|
|
|
|
## 与 GitHub CLI 对比
|
|
|
|
| 操作 | GitHub CLI | Gitee CLI |
|
|
|---|---|---|
|
|
| 认证 | `gh auth login` | `gitee auth login` |
|
|
| 列出仓库 | `gh repo list` | `gitee repo list` |
|
|
| 查看 issue | `gh issue view 1` | `gitee issue view IHWYFN --repo owner/repo` |
|
|
| 创建 PR | `gh pr create` | `gitee pr create --head branch` |
|
|
| 裸 API | `gh api /repos/...` | `gitee api GET /v5/repos/...` |
|
|
|
|
主要区别：Gitee 的 issue 编号是字母格式，且 `--repo` 需要显式指定（除非在仓库目录内）。
|
|
|
|
## 参考
|
|
|
|
- [Gitee API v5 文档](https://gitee.com/api/v5/swagger)
|
|
- [GitHub 仓库](https://github.com/shazhou-ww/gitee-cli)
|