gitcode-cli

简体中文 | English

面向工程师和 AI Agent 的 GitCode 自动化 CLI：用接近 GitHub CLI (gh) 的命令形态，把仓库、Issue、Pull Request、文件、Release、认证、JSON 输出和浏览器跳转变成稳定、可脚本化、适合 Agent 调用的工作流。

快速开始 · 安装 · 认证 · Agent Skill · 常用工作流 · 测试 · English

项目亮点

• gh 风格命令：保留 GitHub CLI 用户熟悉的 repo、issue、pr、release、api 等操作心智。
• Agent-ready：内置 companion skill，指导 Agent 使用稳定 JSON、显式仓库参数和安全确认流程。
• 自动化优先：--json、--jq、--template 和 gc api 适合脚本、CI 和 Agent 推理。
• 低惊讶写操作：merge、delete、release cleanup 等高风险操作在非交互环境中需要显式 --yes。
• 本地 git 组合：clone、checkout、diff、push 等传输动作交给本机 git，平台对象通过 GitCode API 操作。

快速开始

让 Agent 自动安装

如果你希望 Codex 或其他编码 Agent 自动安装本工具，可以直接把下面这段话发给 Agent：

请在当前电脑/开发环境中安装并验证 gitcode-cli：
1. 检查 Node.js 和 npm 是否可用，Node.js 需要 >= 20。
2. 运行 `npm install -g @plm-cac/gitcode-cli`。
3. 验证 `gc --version`、`gitcode --version` 和 `gc --help`。
4. 运行 `gc skill status --json`，然后运行 `gc skill install --yes` 安装配套 Agent skill。
5. 再次运行 `gc skill status --json` 汇报结果。
6. 如果需要登录 GitCode，运行 `gc auth status` 检查状态；不要让我在聊天中粘贴 Token，请让我在本机交互输入或设置 `GITCODE_TOKEN`。

也可以把完整安装文档发给 Agent：Agent install prompt。安装完成后，Agent 可以通过 gc skill status --json 判断 skill 是否已经就位，并优先使用 --json 输出、显式仓库参数和安全确认流程。

适合做什么

| 场景 | 能力 | | --- | --- | | 仓库自动化 | 查看、克隆、创建、fork、同步仓库，设置默认仓库上下文。 | | Issue / PR 工作流 | 列表、查看、创建、编辑、评论、关闭、重开、checkout、diff、merge。 | | 文件和 Release | 浏览仓库文件，查看文件内容，管理 label 和 release。 | | 账号和组织 | 登录、Token 状态、组织仓库、成员、SSH key 管理。 | | JSON 和脚本 | --json、--jq、--template、gc api，方便脚本和 CI 解析。 | | Agent 安全自动化 | 通过 skills/gitcode-cli 指导 Agent 先读后写、显式确认破坏性操作、优先稳定 JSON 输出。 | | 浏览器交接 | gc browse 打开或打印 GitCode URL，适合人机协作。 |

安装

从仓库安装：

npm install
npm run build
npm link
gc --version
gitcode --version

从已发布 npm 包安装：

npm install -g @plm-cac/gitcode-cli
gc --help

认证

交互式登录会在 stderr 明确提示 Token 创建地址和所需权限，并在保存前验证 Token：

gc auth login
gc auth status

创建 Token：https://gitcode.com/setting/token-classic/create

所需权限：api, read_user

脚本友好的登录方式仍然支持从 stdin 读取 Token：

gc auth login --with-token < token.txt

环境变量 Token 优先级高于本地保存的凭据：

GITCODE_TOKEN=... gc issue list -R gcw_CSGJYRfL/test --json number,title

支持的环境变量名包括 GITCODE_TOKEN、GC_TOKEN 和 GITCODE_ACCESS_TOKEN。保存的凭据使用用户配置目录，Token 不会写入 git remote。

Agent Skill

仓库内置了一个一等公民的 Agent skill：

skills/gitcode-cli/SKILL.md

它会提醒 Agent 优先使用只读命令、稳定 JSON 字段和显式仓库参数；在执行 issue close、pr merge、ssh-key delete、label delete、release delete 等变更或破坏性操作前，需要明确用户意图。

如果 CLI 已安装，使用内置安装器：

gc skill status
gc skill install

如果用户先安装了 skill，它也会要求 Agent 先检查 gc 或 gitcode 命令是否存在，并在缺失时引导用户安装 @plm-cac/gitcode-cli。

常用工作流

仓库命令：

gc repo view -R gcw_CSGJYRfL/test --json name,defaultBranchRef
gc repo list gcw_CSGJYRfL
gc repo clone gcw_CSGJYRfL/test -- --depth 1
gc repo set-default gcw_CSGJYRfL/test

Issue 和 Pull Request 命令：

gc issue list --state open --json number,title
gc issue view 12 --comments
gc issue create --title "Bug title" --body-file issue.md
gc issue close 12 --comment "Fixed"

gc pr list --state open --base main --json number,title,headRefName
gc pr view 12 --comments
gc pr create --title "Feature" --body-file pr.md --base main --head feature/x
gc pr checkout 12
gc pr diff 12 --name-only
gc pr merge 12 --squash --delete-branch --yes

文件、组织、SSH key 和 Release 命令：

gc file list -R gcw_CSGJYRfL/test src --json path,type
gc file view -R gcw_CSGJYRfL/test README.md

gc org list --json login,name
gc org repos gcw_CSGJYRfL --json fullName
gc ssh-key list --json id,title
gc ssh-key add --title laptop --key-file ~/.ssh/id_ed25519.pub

gc label list
gc release list
gc release delete v1.0.0 --cleanup-tag --yes
gc search issues "sandbox marker" -R gcw_CSGJYRfL/test --state open
gc browse -R gcw_CSGJYRfL/test issues

底层 API 访问：

gc api repos/gcw_CSGJYRfL/test/issues
gc api --paginate repos/gcw_CSGJYRfL/test/issues --json number,title
gc api -X POST repos/OWNER/REPO/issues -f title="Hello" -f body="Body"

JSON、jq 和模板：

gc issue list -R gcw_CSGJYRfL/test --json number,title --jq '.[0].title'
gc pr list -R gcw_CSGJYRfL/test --template '{{range .}}#{{.number}} {{.title}}
{{end}}'

工作流辅助命令：

gc workflow init -R OWNER/REPO --commit-message "Initial commit"
gc workflow push --set-upstream
gc workflow diff --staged --name-only

效率工具：

gc config set pager false
gc alias set bugs "issue list --state open --json number,title"
gc bugs
gc completion zsh

兼容边界

这个 CLI 借用 gh 的命令形态来降低迁移和记忆成本，但不承诺逐字节兼容。稳定 JSON 输出和 GitCode API 行为优先于完全复刻 GitHub CLI。

外部命令只要命名为 gc-<name> 并出现在 PATH 中，就会被视为扩展命令执行。没有 GitCode 等价能力的 GitHub-only 产品区会明确失败，或仅在 GitCode 有稳定自动化场景时通过外部扩展实现。

GitCode 当前 Release API 没有 release-only 删除端点。gc release delete TAG 在不可用时会给出说明；只有显式传入 --cleanup-tag --yes 时，才会删除支撑该 release 的 Git tag。其他破坏性操作，例如 gc pr merge、gc label delete、gc ssh-key delete，在非交互会话中也需要 --yes。

更多边界请看：

• gh compatibility matrix
• GitCode CLI compatibility boundary

测试

默认测试会构建 TypeScript 项目并使用 mock HTTP server，不会修改真实 GitCode 数据：

npm test

只运行 mock E2E 合同：

npm run test:e2e:mock

只读 live smoke tests 需要显式启用，目标仓库为 https://gitcode.com/gcw_CSGJYRfL/test：

GITCODE_LIVE=1 npm test

认证写入探针是单独的、偏 cleanup 的测试：

GITCODE_LIVE_WRITES=1 GITCODE_TOKEN=... npm test

真实仓库创建是单独的 opt-in E2E，因为它会创建并删除一个临时私有仓库：

GITCODE_LIVE_REPO_CREATE=1 GITCODE_TOKEN=... npm run test:e2e:live-repo

更多测试合同格式、mock server helper、mock git harness 和 live repo cleanup 行为，请看 E2E testing framework。

相关文档

• 项目定位
• CHANGELOG
• gh compatibility matrix
• Compatibility boundary
• Agent skill
• E2E testing framework

English

Back to Chinese

gitcode-cli is an automation-focused GitCode CLI for engineers and AI agents. It uses a GitHub CLI (gh)-like command shape to make repositories, issues, pull requests, files, releases, auth, JSON output, and browser handoff predictable from terminals, scripts, CI, and agent workflows.

Quick Start · Install · Authenticate · Agent Skill · Daily Workflows · Testing · Back to Chinese

Highlights

• gh-style commands: keep the familiar repo, issue, pr, release, and api mental model for GitHub CLI users.
• Agent-ready: ships a companion skill that guides agents toward stable JSON, explicit repository arguments, and safety checks.
• Automation-first: --json, --jq, --template, and gc api work well for scripts, CI, and agent reasoning.
• Low-surprise writes: high-risk operations such as merge, delete, and release cleanup require explicit --yes in non-interactive sessions.
• Composes with local git: transport actions such as clone, checkout, diff, and push use local git; platform objects go through the GitCode API.

Quick Start

Agent-assisted Install

If you want Codex or another coding agent to install this tool for you, paste this prompt into the agent:

Please install and verify gitcode-cli in the current machine/development environment:
1. Check that Node.js and npm are available. Node.js must be >= 20.
2. Run `npm install -g @plm-cac/gitcode-cli`.
3. Verify `gc --version`, `gitcode --version`, and `gc --help`.
4. Run `gc skill status --json`, then run `gc skill install --yes` to install the companion Agent skill.
5. Run `gc skill status --json` again and report the result.
6. If GitCode login is needed, run `gc auth status`; do not ask me to paste a token into chat. Ask me to enter it interactively on my machine or set `GITCODE_TOKEN`.

You can also send the full install document to the agent: Agent install prompt. After installation, agents can use gc skill status --json to verify the skill is ready, then prefer --json output, explicit repository arguments, and confirmation-aware mutation flows.

What It Automates

| Area | Capability | | --- | --- | | Repository automation | View, clone, create, fork, and sync repositories, and save default repository context. | | Issue / PR workflows | List, view, create, edit, comment, close, reopen, checkout, diff, and merge. | | Files and releases | Browse repository files, view file content, and manage labels and releases. | | Account and organization | Login, token status, organization repositories, members, and SSH keys. | | JSON and scripts | Use --json, --jq, --template, and gc api for scripts and CI. | | Agent-safe automation | Use skills/gitcode-cli to guide agents toward read-first flows, explicit confirmation, and stable JSON output. | | Browser handoff | Use gc browse to open or print GitCode URLs for human-agent collaboration. |

Install

From the repository:

npm install
npm run build
npm link
gc --version
gitcode --version

From a published package:

npm install -g @plm-cac/gitcode-cli
gc --help

Authenticate

Interactive login prints the token creation URL and required scopes on stderr, then validates the token before saving it:

gc auth login
gc auth status

Create a token at: https://gitcode.com/setting/token-classic/create

Required scopes: api, read_user

Script-friendly login still reads from stdin:

gc auth login --with-token < token.txt

Environment tokens take precedence over saved credentials:

GITCODE_TOKEN=... gc issue list -R gcw_CSGJYRfL/test --json number,title

Supported environment variable names are GITCODE_TOKEN, GC_TOKEN, and GITCODE_ACCESS_TOKEN. Saved credentials use the user config directory, and tokens are never embedded in git remotes.

Agent Skill

The repository ships a first-class agent skill:

skills/gitcode-cli/SKILL.md

It nudges agents toward read-only commands first, stable JSON fields, and explicit repository arguments. It also documents when to prompt before mutating GitCode state, including issue close, pr merge, ssh-key delete, label delete, and release delete.

If the CLI is already installed, use the built-in installer:

gc skill status
gc skill install

If the skill was installed first, it instructs the agent to verify that gc or gitcode exists and ask the user to install @plm-cac/gitcode-cli before running GitCode commands.

Daily Workflows

Repository commands:

gc repo view -R gcw_CSGJYRfL/test --json name,defaultBranchRef
gc repo list gcw_CSGJYRfL
gc repo clone gcw_CSGJYRfL/test -- --depth 1
gc repo set-default gcw_CSGJYRfL/test

Issue and pull request commands:

gc issue list --state open --json number,title
gc issue view 12 --comments
gc issue create --title "Bug title" --body-file issue.md
gc issue close 12 --comment "Fixed"

gc pr list --state open --base main --json number,title,headRefName
gc pr view 12 --comments
gc pr create --title "Feature" --body-file pr.md --base main --head feature/x
gc pr checkout 12
gc pr diff 12 --name-only
gc pr merge 12 --squash --delete-branch --yes

File, org, SSH key, and release commands:

gc file list -R gcw_CSGJYRfL/test src --json path,type
gc file view -R gcw_CSGJYRfL/test README.md

gc org list --json login,name
gc org repos gcw_CSGJYRfL --json fullName
gc ssh-key list --json id,title
gc ssh-key add --title laptop --key-file ~/.ssh/id_ed25519.pub

gc label list
gc release list
gc release delete v1.0.0 --cleanup-tag --yes
gc search issues "sandbox marker" -R gcw_CSGJYRfL/test --state open
gc browse -R gcw_CSGJYRfL/test issues

Lower-level API access:

gc api repos/gcw_CSGJYRfL/test/issues
gc api --paginate repos/gcw_CSGJYRfL/test/issues --json number,title
gc api -X POST repos/OWNER/REPO/issues -f title="Hello" -f body="Body"

JSON, jq, and templates:

gc issue list -R gcw_CSGJYRfL/test --json number,title --jq '.[0].title'
gc pr list -R gcw_CSGJYRfL/test --template '{{range .}}#{{.number}} {{.title}}
{{end}}'

Workflow helpers:

gc workflow init -R OWNER/REPO --commit-message "Initial commit"
gc workflow push --set-upstream
gc workflow diff --staged --name-only

Productivity helpers:

gc config set pager false
gc alias set bugs "issue list --state open --json number,title"
gc bugs
gc completion zsh

Compatibility Boundary

This CLI borrows gh command shapes where they make GitCode automation easier, but it does not promise byte-for-byte gh parity. Stable JSON output and GitCode API behavior take priority.

External commands named gc-<name> on PATH are treated as extensions. GitHub-only product areas without GitCode equivalents fail clearly, or should be implemented as external extensions only when GitCode has a stable automation workflow.

GitCode does not expose a release-only delete endpoint in the current release API. gc release delete TAG will fail with guidance when release-only deletion is unavailable; pass --cleanup-tag --yes to delete the tag that backs the release. Other destructive operations such as gc pr merge, gc label delete, and gc ssh-key delete also require --yes in non-interactive sessions.

See:

• gh compatibility matrix
• GitCode CLI compatibility boundary

Testing

Default tests build the TypeScript project and use mock HTTP servers, so they do not mutate live GitCode data:

npm test

Mock-only E2E contracts can be run directly:

npm run test:e2e:mock

Read-only live smoke tests are opt-in and target https://gitcode.com/gcw_CSGJYRfL/test:

GITCODE_LIVE=1 npm test

Authenticated write probes are separate and cleanup-oriented:

GITCODE_LIVE_WRITES=1 GITCODE_TOKEN=... npm test

Live repository creation is a separate opt-in E2E because it creates and then deletes a real temporary private repository:

GITCODE_LIVE_REPO_CREATE=1 GITCODE_TOKEN=... npm run test:e2e:live-repo

See E2E testing framework for the contract case format, mock server helpers, mock git harness, and live repo cleanup behavior.

Related Docs

• Positioning decision
• CHANGELOG
• gh compatibility matrix
• Compatibility boundary
• Agent skill
• E2E testing framework