# gh 参考手册（渐进披露）

主说明见 [SKILL.md](SKILL.md)。此处补充常用命令与非交互参数。

## 全局

| 用途 | 示例 |
|------|------|
| 帮助 | `gh <command> --help` |
| 指定仓库 | `-R owner/repo` 或在仓库目录执行 |
| JSON 输出 | `--json field1,field2` |
| jq 过滤 | `--jq 'select(.state=="OPEN")'` |

## auth

```bash
gh auth status
gh auth login
gh auth token
```

## repo

```bash
gh repo view --json name,owner,url,description
gh repo clone owner/name
gh repo create name --public --source=. --remote=origin --push
```

## issue

```bash
gh issue list --state open --limit 50
gh issue list --json number,title,labels,assignees
gh issue view 123 --json body,author,comments
gh issue create --title "t" --body "b" --label bug
gh issue close 123
```

## pr

```bash
gh pr list --state open
gh pr view 42 --json title,body,commits,files
gh pr checkout 42
gh pr diff 42
gh pr merge 42 --squash --delete-branch
```

合并时若需避免编辑器：使用 `--title`/`--body` 与明确的合并策略标志。

## workflow / run

```bash
gh workflow list
gh run list --workflow "ci.yml" --limit 10
gh run view <run-id>
gh run watch <run-id>
gh run rerun <run-id>
```

## release

```bash
gh release list
gh release view v1.2.3
gh release create v1.2.3 ./dist/*.zip --notes "..."
```

## api

```bash
# GET
gh api user

# 带查询参数
gh api repos/{owner}/{repo}/pulls --paginate

# POST（示例）
gh api repos/{owner}/{repo}/issues -f title="x" -f body="y"
```

GraphQL 使用 `gh api graphql -f query='...'`（复杂查询优先查 GitHub 文档）。

## JSON 字段提示

不同子命令可用字段以 `gh <cmd> list --json` 的帮助为准。常见：

- `gh pr list --json`: `number,title,state,headRefName,baseRefName,author,url`
- `gh issue list --json`: `number,title,state,labels,assignees,author`

## CI 环境变量

- `GH_TOKEN`：非交互调用时常用（注意最小权限原则）。
- 具体行为以当前 `gh` 版本文档为准。