gitea-cli

通过 Gitea HTTP API 操作 Git 仓库的命令行工具。支持分支、文件内容、工单、PR、标签、Actions、Webhook、Release 等全量操作。

TypeScript 实现，单文件 ESM bundle，通过 npm 分发。

特性

• 多 context 配置，支持多个 Gitea 实例
• JSON / 表格双模式输出，适合脚本和人工查看
• 无状态 API 调用，可并发安全使用
• 三级配置加载（CLI flag → 工作区 .gitea-cli.yaml → 全局 config）
• git remote 自动检测 host/owner/repo/branch
• 单 npm 包发布，零跨平台 binary

安装

npm install -g gitea-cli-skill

或一次性使用：

npx gitea-cli-skill@latest <command>

要求 Node 18+。npm 包名是 gitea-cli-skill，安装后命令是 gitea-cli（包名 ≠ bin 名 是 npm 常见做法）。

快速开始

1. 配置 context

gitea-cli config set --name work \
  --host https://git.example.com \
  --token your-api-token \
  --default-owner myorg

# 带默认 repo
gitea-cli config set --name work \
  --host https://git.example.com \
  --token your-api-token \
  --default-owner myorg \
  --default-repo myrepo

不想用命令行？也可以手写 ~/.config/gitea-cli/config.yaml（Windows 用 %APPDATA%\gitea-cli\config.yaml）：

current-context: work
contexts:
  - name: work
    host: https://git.example.com
    token: "your-api-token"
    default-owner: "myorg"

2. 检查安装状态

gitea-cli doctor

3. 验证连通性

gitea-cli repo list --owner myorg

4. 常用操作

gitea-cli branch create feature/abc --from main
gitea-cli issue create --title "Bug" --body "detail"
gitea-cli pr create --title "feat: xxx" --head feature/abc --base main

5. （可选）安装 AI 平台 skill 文档

把 SKILL 文档复制到 Claude / Cursor / Codex 等平台的 skill 目录。默认会装两个 skill：

• gitea-cli：工具层。API 命令速查、--output json 字段说明、错误处理
• gitea-issue：业务层。Issue/PR 全生命周期工作流、标签/里程碑管理规范

# 默认: 装到当前项目的 .claude/skills/ (gitea-cli + gitea-issue 一起)
gitea-cli init

# 指定平台
gitea-cli init --platform cursor
gitea-cli init --platform codex

# 装到 $HOME 而非项目目录
gitea-cli init --global

# 一次性装到所有支持的平台
gitea-cli init --platform all

# 自定义目录（覆盖 --platform 路径）
gitea-cli init --target /custom/path

# 只装其中一个 skill
gitea-cli init --skill gitea-cli         # 只工具层
gitea-cli init --skill gitea-issue       # 只业务层

支持的平台：claude / cursor / windsurf / antigravity / copilot / kiro / codex / qoder / roocode / gemini / trae / opencode / continue / codebuddy / droid / kilocode / warp / augment

完整命令参考见 AGENTS.md。

从源码构建

npm install
npm run build
node dist/cli.js --help

测试

npm test                  # vitest 单测，155 cases (13 files)，约 3s
npx tsc --noEmit          # 类型检查

配置文件

默认路径：

• Linux/macOS：~/.config/gitea-cli/config.yaml
• Windows：%APPDATA%\gitea-cli\config.yaml

格式：

current-context: work
contexts:
  - name: work
    host: https://git.company.com
    token: "your-api-token"
    default-owner: "myorg"
  - name: personal
    host: https://gitea.io
    token: "your-api-token"
    default-owner: "myname"

工作区配置 .gitea-cli.yaml

在项目根目录创建（与 .git/ 同级），向上搜索：

host: https://gitea.company.com   # 此项目使用的服务器
token: bot-token-here             # 项目专用 bot token（建议加入 .gitignore）
owner: myorg                      # 默认 owner
context: work                     # 引用全局 config 中的 context

三级配置优先级

                      ┌─────────────────────────────┐
运行时               │  --flag / GITEA_* env var    │  (最高优先级)
                      └──────────────┬──────────────┘
                                     │
                      ┌──────────────▼──────────────┐
工作区               │  .gitea-cli.yaml              │  向上搜索至文件系统根
                      └──────────────┬──────────────┘
                                     │
                      ┌──────────────▼──────────────┐
git auto-detect      │  git remote get-url origin   │  解析 host / owner / repo
                      └──────────────┬──────────────┘
                                     │ host → 自动匹配 context
                      ┌──────────────▼──────────────┐
全局配置             │  ~/.config/gitea-cli/config.yaml│  (最低优先级)
                      └─────────────────────────────┘

全局选项

| Flag | 简写 | 说明 | |------|------|------| | --config | | 配置文件路径 | | --context | -c | 临时切换 context | | --host | | 覆盖 Gitea 地址 | | --token | | 覆盖 API Token | | --output | -o | json 或 table（默认 table） | | --owner | | 仓库 owner | | --repo | -r | 仓库名 | | --error-log | | 错误日志目录（默认 ~/.gitea-cli） |

输出格式

所有命令默认表格输出。使用 --output json 获取 JSON：

gitea-cli issue list --output json --owner myorg --repo myrepo | jq '.[].title'

错误信息以 JSON 写到 stderr（JSON 模式）：

{"error": "API 404: repository not found"}

Windows PowerShell 用户：默认控制台 codepage 是 GBK（936），管道传 JSON 给下游会乱码非 ASCII 字符。gitea-cli 检测到风险时会在 stderr 输出一行提示，按提示设置 $OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new() 即可。gitea-cli doctor 也会显示当前 codepage。

Git 工作区自动检测

在 git 仓库目录内运行时，gitea-cli 自动从 origin remote URL 解析 host/owner/repo：

# 在 /path/to/your-project 内（git remote = https://gitea.example.com/org/repo.git）
gitea-cli issue list          # 等同于 --owner org --repo repo
gitea-cli pr list
gitea-cli branch list

支持的 remote URL 格式：

• HTTPS: https://[user:pass@]host[:port]/owner/repo[.git]
• SSH (scp 形式): git@host:owner/repo[.git]
• SSH (URL 形式): ssh://[user@]host[:port]/owner/repo[.git]

SSH 端口推断成 HTTPS 时会被丢弃（绝大多数 Gitea 部署的 API 跑在 443/80，与 SSH 端口不同）。若你的部署 SSH 和 HTTPS 在不同主机/端口，请用 --host 或工作区配置覆盖。

对涉及分支的命令（commit list、content create/update/delete、actions workflow dispatch），省略 --branch/--ref 时自动使用当前 git 分支。

命令分组

gitea-cli --help 把命令分为三组：

Common Commands:
  branch      管理分支
  commit      查看提交历史
  content     管理文件内容
  download    从 Gitea Release 下载二进制
  issue       管理工单（含评论、附件）
  label       管理 Label
  milestone   管理 Milestone
  pr          管理 Pull Request
  release     管理 Release（含 asset 上传/下载）
  repo        查看仓库信息

CI/CD Commands:
  actions     管理 Gitea Actions（workflow / run / job / artifact）
  tag         管理 Tag
  webhook     管理 Webhook

Configuration & Admin:
  config         管理 context 配置（list / set / switch / remove）
  init           初始化 skill（安装 SKILL.md 到 AI 平台目录）
  doctor         检查 gitea-cli 安装状态
  cleanup-legacy 清理 v0.5.x 时代遗留的 Go 二进制

完整命令速查见 AGENTS.md。

发布流程

推荐：一键脚本

bash scripts/release.sh patch     # hotfix, 2.0.1 → 2.0.2
bash scripts/release.sh minor     # 新特性, 2.0.x → 2.1.0
bash scripts/release.sh 3.0.0     # 显式版本
bash scripts/release.sh patch --dry-run   # 全程预演，零副作用

脚本会自动 build、跑测试、改版本号、commit、tag、push、npm publish、在 Gitea 上创建 release。详见 scripts/README.md。

也支持 CI 自动发布：本地 git tag v2.x.y && git push --tags 之后，.gitea/workflows/release.yml 会接管剩余步骤（要求 Gitea 仓库已注册 act_runner 且 NPM_TOKEN secret 已配置）。预发布 tag（如 v2.1.0-rc.0）走 npm 的 next dist-tag，正式版本走 latest。

目录结构

.
├── src/
│   ├── cli.ts                  # commander 入口
│   ├── cli/                    # 命令组（commander 子命令）
│   ├── api/                    # HTTP client + types + 资源模块
│   ├── config/                 # 配置文件读写
│   ├── git/detect.ts           # git remote 解析
│   ├── legacy/detect.ts        # v0.5.x Go 二进制检测
│   ├── win/encoding.ts         # Windows console codepage 检测
│   ├── output/printer.ts       # JSON + table 渲染
│   └── skill_assets/           # SKILL.md（build 时嵌入）
├── test/unit/                  # vitest 单测（13 files, 155 cases）
├── doc/
│   ├── references/swagger.json # Gitea API 参考（301 个端点）
│   ├── spec/                   # 产品 / 技术方案文档
│   └── usage/                  # 使用指南
├── scripts/                    # 发布脚本（release / bump / npm-publish）
├── AGENTS.md                   # AI agents 工作指南（命令速查）
└── README.md

开发路线图

| Phase | 状态 | 内容 | |-------|------|------| | 1 | ✅ | 分支、文件内容、工单（含评论、附件） | | 2 | ✅ | Tag、Gitea Actions（workflow/run/job/artifact） | | 3 | ✅ | Pull Request、Label、Milestone | | 4 | ✅ | Webhook（list/get/create/delete/test） | | 5 | ✅ | Release（list/get/create/delete + asset 管理） | | 6 | ✅ | TypeScript 重写（单文件 ESM npm 包） | | 7 | ✅ | Windows PowerShell UTF-8 提示、cleanup-legacy、config set/switch/remove | | 8 | 计划中 | pr update 子命令、E2E 集成测试、Go vs Node JSON 字节级 fixture 回归网 |