# gitee_cli

**Repository Path**: Yoshiera/gitee_cli

## Basic Information

- **Project Name**: gitee_cli
- **Description**: Agent-native Gitee CLI (JSON-first, mirrors Gitee API v5)
- **Primary Language**: Unknown
- **License**: Unlicense
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gee — Gitee CLI

Agent-native Gitee CLI（JSON-first）。对标 GitHub `gh`，镜像 Gitee API v5，用 Rust
编写。**输出天然双形态**：管道/脚本/agent 调用拿到原始 JSON，交互终端自动渲染人读表格。

## 特性

- **JSON-first**：stdout 输出原始 Gitee API v5 JSON，agent 直接消费，对照
  [Gitee API v5 swagger](https://gitee.com/api/v5/swagger) 即知结构。
- **isatty 自动切换**：终端里自动渲染对齐表格（tabled），管道/重定向保持原始 JSON，
  `--pretty` 在管道场景强制表格。
- **类型化命令**：15 组命令覆盖仓库/Issue/PR/里程碑/标签/分支/Tag/Release/搜索/用户/
  组织/通知，参数校验 + `--repo` 从 git remote 推导 + 分页聚合 + 错误映射。
- **万能后门**：`gee api <path>` 透传全部 API v5 端点。
- **完整测试**：182 个测试（单元 + httpmock 集成 + 命令层 assert_cmd），真实 payload
  fixtures 驱动输出形状验证。

## 安装

```bash
cargo install --path .
```

需要 Rust 1.70+（依赖 `std::io::IsTerminal`）。

## 快速开始

```bash
# 认证（PAT）
export GITEE_TOKEN=<personal-access-token>   # 优先级最高
gee auth status                               # 验证并打印当前用户 JSON
gee auth login --token <T>                    # 写入 ~/.config/gee/config.json
```

Token 生成：<https://gitee.com/profile/personal_access_tokens>

## 配置

配置文件：`~/.config/gee/config.json`（可用 `GE_CONFIG_PATH` 覆盖）。

```bash
gee config set owner <owner>   # 设置默认 owner（repo list 等缺省浏览视角）
gee config get                 # 查看当前配置与配置文件路径
```

- `owner` 是**可选的默认浏览视角**：设置后 `gee repo list` 列出该 owner 的仓库；
  不设置则列出当前认证账号的仓库。`auth login` 会自动写入当前账号。
- 单独查看某人/某组织的公开仓库：`gee repo list --owner <owner>`（无需配置）。

## 常用命令

```bash
gee repo list --owner openharmony     # 列表（终端里自动出表格，管道出 JSON）
gee repo view --repo owner/name       # 详情（--repo 缺省取 git remote origin）
gee repo update --repo owner/name --description "new desc"   # 改仓库元数据
gee issue list [--state open] [--paginate]
gee issue view 123
gee issue create --title "bug" --body "详情"
gee pr list [--state merged]
gee pr create --title "feat" --head feature-branch --base master
gee release upload v1.0.0 --file ./dist/app.tar.gz --clobber
gee search repos "rust gitee"
gee api repos/owner/name/pulls        # 万能后门
```

完整命令组：`auth` `api` `repo` `issue` `milestone` `label` `pr` `branch` `tag`
`release` `search` `user` `org` `config` `notification` `webhook` `commit` `gist`
`content` `collaborator` `keys` `git` `check-run` `comment` `fork` `watch` `follower`
`membership` `namespace` `event` `enterprise` `license` `gitignore` `markdown`。每个命令 `--help` 查看参数。

## 输出契约

| 场景 | 输出 |
|------|------|
| 交互终端（TTY） | 人读对齐表格（自动） |
| 管道 / 重定向 / agent | 原始 Gitee JSON |
| `--pretty` | 强制表格（管道场景也可用） |

表格默认只显示每类命令的精简列（如 `repo list` → full_name/language/stargazers_count/default_branch），
可用 `--fields a,b,c` 覆盖；**每个列表命令 `--help` 底部列出该命令可用的全部字段**：

```bash
gee repo list --fields name,stargazers_count   # 只看这两列
gee issue list --help                          # 底部显示 Available --fields: number, title, state, ...
gee issue list --fields number,title,state
```

错误映射：非 2xx → `[status] message`（取自 `{"message": ...}`），stderr，退出码非零。
元信息（rate limit/status）走 stderr，仅 `--verbose` 显示。

## 开发

```bash
cargo build && cargo test    # 302 tests
```

- 架构与设计：`DESIGN.md`、`HANDOFF.md`
- 测试：单元测试 + httpmock 集成 + assert_cmd 命令层；真实 payload 存 `tests/fixtures/`
- CI：`.workflow/default.yml`（Gitee Go 官方 Rust 模板，`step: build@rust` + `cargo test --locked`，master push 触发）
- Agent skill：`SKILL.md` + `references/`（ge 式渐进披露）内嵌进二进制；
  `gee skill install` 部署到各 agent 平台目录，`gee skill doctor` 校验一致性

## License

Public domain (Unlicense) — do whatever you want. See [LICENSE](LICENSE).