Skip to content

chatgh Docs

chatgh is the ChatArch GitHub CLI and Python API package. It carries the PR, CI, Actions run/job log, repository permission, and token configuration features migrated from chattool gh. New scripts and docs should call chatgh directly; chattool gh is only a ChatTool-side compatibility entry point.

Installation

pip install chatgh
# development
pip install -e ".[dev]"

Configuration Model

Default behavior:

  • repo: explicit --repo owner/repo wins; otherwise chatgh infers the repository from the current git remote.
  • token: explicit --token wins, then the repo-local HTTPS auth header in the current repository's .git/config, then GITHUB_ACCESS_TOKEN from typed env.
  • Output: human-readable by default; commands with --json FIELDS emit official gh-style field-projected JSON, while --json-output remains available as a full payload JSON dump for scripts.

Token Sources

Token resolution order is stable:

  1. Explicit --token.
  2. Repo-local HTTPS auth header in the current repository's .git/config, with the path normalized to https://github.com/owner/repo.git.
  3. GITHUB_ACCESS_TOKEN from typed env.

Use chatenv to inspect or configure typed env:

chatenv init -t gh
chatenv cat -t gh

After chatgh is installed, it registers GitHubConfig through the chatenv.configs entry point, so chatenv list shows a [GitHub] group and -t gh / -t github resolve to the same GitHub typed env.

ghp_xxx and github_pat_xxx are GitHub Personal Access Tokens. Clone/fetch/push usually require contents read/write permissions; PR comments, merges, and Actions inspection may require additional repository permissions.

Repository Inference

When --repo is omitted, chatgh checks git remotes in the current repository. It tries origin first, then other remotes. Supported forms:

  • https://github.com/octocat/Hello-World.git
  • https://github.com/octocat/Hello-World
  • git@github.com:octocat/Hello-World.git
  • ssh://git@github.com/octocat/Hello-World.git

When writing a repo-local HTTPS auth header, the path is normalized to https://github.com/octocat/Hello-World.git.

CLI Entry Points

Docs navigation:

  • Docs site: https://arch.gh.wzhecnu.cn/ChatGH/, maintained in mkdocs.yml as site_url.
  • Docs language: use mkdocs-static-i18n suffix mode. Chinese is the default site; English mirror files use the .en.md suffix and are generated under /en/. Do not split Chinese and English into separate nav trees.
  • docs/interface-tree.en.md: current CLI tree, target direction, responsibilities, and CLI -> Python API mapping, aligned with the ChatTea / ChatZulip interface-tree style.
  • docs/gh-interface-alignment.md: official gh alignment rules, layering, and test requirements.
  • docs/agent-definition.en.md: ChatGH agent/robot definition, manifest, flow, permissions, and runtime boundaries.
  • docs/agent-task-bot-alignment.en.md: research on official gh agent-task, gh skill, GitHub Apps, webhooks, bot patterns, and ChatGH's agent-task/bot direction.
chatgh --help
chatgh --tree
chatgh pr --help
chatgh repo --help
chatgh invitation --help
chatgh project --help
chatgh run --help
chatgh repo-perms --help
chatgh set-token --help

Command tree (chatgh --tree renders the full registered Click tree live):

  • chatgh --tree: print the current registered command tree with signatures and one-line purposes for release acceptance/readback.
  • chatgh pr list/create/view/comment/edit/checks/merge: existing PR workflow commands; merge defaults to --check and must not be used as a dry-run.
  • chatgh pr status/diff/close/reopen/review/ready/update-branch: common lifecycle/review commands added in this batch; write commands use ChatGH token resolution and keep secrets out of output.
  • chatgh repo list/create/fork/transfer/protection: repository list/create/fork/ownership-transfer/protection commands.
  • chatgh repo view/clone/sync/edit: common repository commands added in this batch; clone/sync keep local git side effects explicit and conservative.
  • chatgh invitation list/accept/decline: view and handle repository invitations for the authenticated GitHub user, aligned with GitHub REST API invitation endpoints.
  • chatgh project list/view/create/edit/close/delete/copy, chatgh project item ..., chatgh project field ..., and link/unlink/mark-template: GitHub Projects v2 commands. Official gh project is only a capability reference; ChatGH opens native item and field subtrees and does not keep flat item-add / field-list compatibility entries. Auth, JSON output, safety gates, and Python APIs follow ChatGH conventions.
  • chatgh run view/logs: workflow run and job-log inspection.
  • chatgh run list/watch/rerun/cancel/download: Actions run operations added in this batch; watch has a timeout and rerun/cancel are real remote mutations.
  • chatgh repo-perms: show token permissions and derived capabilities.
  • chatgh set-token: configure a repo-scoped HTTPS token for the current GitHub repository.

Common Workflows

Repo View / Clone / Sync / Edit

chatgh repo view ChatArch/ChatGH --json-output
chatgh repo clone ChatArch/ChatGH ./ChatGH-copy
chatgh repo sync --repo ChatArch/ChatGH --branch master --remote origin --json-output
chatgh repo edit ChatArch/ChatGH --description "GitHub helpers" --json-output
chatgh repo edit ChatArch/ChatGH --visibility private --accept-visibility-change-consequences --json-output

repo clone refuses to overwrite a non-empty target directory. repo sync defaults to git pull --ff-only and refuses to sync a mismatched explicit repository from the wrong checkout. repo edit currently supports description, homepage, default branch, and visibility; --visibility requires --accept-visibility-change-consequences.

Repository Invitations

chatgh invitation list
chatgh invitation list --json-output
chatgh invitation accept 325100806 --json-output
chatgh invitation decline 325100806 --json-output

invitation uses the current ChatGH token resolution flow to read repository invitations for the authenticated user. accept and decline are remote write operations; they operate only on explicit invitation ids and do not guess or batch-handle invitations.

GitHub Projects

chatgh project list --owner ChatArch --json-output
chatgh project view 3 --owner ChatArch --json-output
chatgh project create --owner ChatArch --title "Roadmap" --json-output
chatgh project item add 3 --owner ChatArch --content-id ISSUE_OR_PR_NODE_ID --json-output
chatgh project item edit 3 --owner ChatArch --id PROJECT_ITEM_ID --field-id FIELD_ID --text "In progress" --json-output
chatgh project field list 3 --owner ChatArch --json-output

project does not replicate the official flat gh project tree. ChatGH organizes Project lifecycle, item, and field separately: project item add/edit/list/... and project field list/create/delete are the main entries, and flat item-add / field-list compatibility aliases are intentionally not kept. ChatGH still does not depend on official gh auth: it uses --token, repo-local tokens, and ChatEnv GITHUB_ACCESS_TOKEN; remote mutations keep ChatGH safety gates; and each CLI command is backed by importable chatgh.github.projects Python APIs. Every recoverable missing-input path in project follows ChatStyle: default auto-prompt, CHATARCH_AUTO_PROMPT=0/false/no/off fail-fast behavior for machine/CI callers, -i force-interactive, and -I no-interactive. Destructive confirmations still require explicit --confirm. project item edit expands GitHub Projects v2 field value types with --text, --number, --date, --single-select-option-id, --iteration-id, and --clear.

PR Lifecycle / Review

chatgh pr status --repo ChatArch/ChatGH --json-output
chatgh pr diff 14 --repo ChatArch/ChatGH
chatgh pr close 14 --repo ChatArch/ChatGH --comment "Superseded" --json-output
chatgh pr reopen 14 --repo ChatArch/ChatGH --json-output
chatgh pr review 14 --repo ChatArch/ChatGH --approve --body-file review.md --json-output
chatgh pr ready 14 --repo ChatArch/ChatGH --json-output
chatgh pr update-branch 14 --repo ChatArch/ChatGH --expected-head-sha SHA --json-output

close/reopen/review/ready/update-branch are remote write operations; confirm the target PR before running them.

Create A PR

chatgh pr create --repo octocat/Hello-World --base main --head rex/feature --title "Add feature" --body-file pr-body.md
chatgh pr create --repo octocat/Hello-World --base main --head rex/feature --title "Add feature" --body "Short body" --json-output

pr create uses the existing ChatGH token resolution flow and does not print tokens. Missing base/head/title values can be prompted interactively; use -I to fail clearly in non-interactive mode.

View PRs

chatgh pr list --repo octocat/Hello-World --state open --limit 20
chatgh pr view 123 --repo octocat/Hello-World
chatgh pr view 123 --repo octocat/Hello-World --json-output

pr view output includes:

  • PR number, title, state, author, and URL.
  • base/head branches.
  • mergeable and mergeable_state.
  • created/updated/merged timestamps.

Inspect CI

chatgh pr checks 123 --repo octocat/Hello-World
chatgh pr checks 123 --repo octocat/Hello-World --json-output

pr checks summarizes three layers for the PR head commit:

  • combined status
  • check runs
  • workflow runs

The public CLI currently does not expose --wait / --interval / --timeout; when a terminal CI result is needed, poll chatgh pr checks from the surrounding workflow.

If the GitHub token cannot access the check-runs API, the command stores that error in the payload while still showing combined status and workflow runs when available.

Inspect Actions Runs And Job Logs

chatgh run list --repo octocat/Hello-World --limit 20
chatgh run watch 123456789 --repo octocat/Hello-World --timeout 600
chatgh run rerun 123456789 --repo octocat/Hello-World --json-output
chatgh run cancel 123456789 --repo octocat/Hello-World --json-output
chatgh run download 123456789 --repo octocat/Hello-World --dir ./artifacts

chatgh run view --repo octocat/Hello-World --run-id 123456789
chatgh run view --repo octocat/Hello-World --run-id 123456789 --json-output

chatgh run logs --repo octocat/Hello-World --job-id 987654321
chatgh run logs --repo octocat/Hello-World --job-id 987654321 --tail 0
chatgh run logs --repo octocat/Hello-World --job-id 987654321 --tail 200 --output job.log

run logs shows tail output by default; --tail 0 prints the full log; --output writes the full log to a file while the terminal still shows the selected tail.

Comment, Merge, And Edit PRs

chatgh pr comment 123 --repo octocat/Hello-World --body-file review-note.md
chatgh pr edit 123 --repo octocat/Hello-World --title "New title" --body-file pr-body.md
chatgh pr merge 123 --repo octocat/Hello-World --method squash --check

pr merge defaults to --method squash and --check, reading PR checks before merge and refusing non-green states. Merging is still a high-risk remote mutation; confirm PR status and user authorization before running it.

Fork Repositories

# gh-like shape
chatgh repo fork octocat/Hello-World --org ChatArch
chatgh repo fork octocat/Hello-World --org ChatArch --fork-name hello-world-copy --default-branch-only

# ChatGH explicit / automation-friendly shape
chatgh repo fork --source octocat/Hello-World --owner ChatArch
chatgh repo fork --source octocat/Hello-World --owner ChatArch --name hello-world-copy --default-branch-only
chatgh repo fork --source octocat/Hello-World --owner ChatArch --if-exists use --json-output

repo fork uses the GitHub Fork API. The target repository name defaults to the source repository name. It accepts the common official gh repo fork [<repository>] --org ... --fork-name ... shape while preserving ChatGH's explicit --source/--owner/--name and --json-output/--if-exists use automation extensions. Organization targets send GitHub's organization field; user-account targets require --owner to match the authenticated user. --if-exists use only reuses an existing fork when it matches the requested source, avoiding false success on an unrelated same-name repository.

Transfer Repository Ownership

chatgh repo transfer ChatArch/ExampleRepo --owner OmniCAS --dry-run --json-output
chatgh repo transfer ChatArch/ExampleRepo --owner OmniCAS --accept-transfer-consequences --json-output

repo transfer uses the GitHub Repository Transfer API to move repository ownership to a target user/org. Unlike repo fork, it preserves repository identity such as issues, PRs, stars, and settings while GitHub handles redirects. Prefer --dry-run first to verify source permissions and that the target same-name repository does not already exist. The real transfer requires --accept-transfer-consequences because it can affect access, webhooks, secrets, GitHub Pages, and automation. For organization transfers, repeat --team-id to grant target teams access after transfer.

Inspect Repository Protection

chatgh repo protection --repo octocat/Hello-World
chatgh repo protection --repo octocat/Hello-World --json-output
chatgh repo protection --owner octocat --limit 50 --jobs 8
chatgh repo protection --owner octocat --limit 50 --jobs 8 --json-output

repo protection reports the default branch, whether it is protected, classic branch protection details such as required PR reviews / review count / force-push and deletion flags, and repository ruleset summaries when GitHub exposes them. Some private repositories may return a GitHub plan/visibility error for rulesets; the command preserves that error in JSON while still reporting the branch protection state when available. Owner inventory mode lists repositories first, then checks each repository concurrently with --jobs while preserving stable output order.

Configure And Inspect Tokens

chatgh repo-perms --repo octocat/Hello-World --json-output
chatgh repo-perms --repo octocat/Hello-World --full-json

chatgh set-token --token "$GITHUB_ACCESS_TOKEN"
chatgh set-token --token "$GITHUB_ACCESS_TOKEN" --save-env

repo-perms shows:

  • token source and masked token.
  • permissions returned by GitHub.
  • derived capabilities: can_read_pr, can_comment_pr, can_merge_pr, can_view_checks, can_view_actions.

set-token only works when the current directory has a recognizable GitHub remote. By default it writes only the current repository's .git/config:

[http "https://github.com/octocat/Hello-World.git"]
    extraHeader = Authorization: Basic <base64(x-access-token:TOKEN)>

Do not put tokens in remote URLs, and do not log raw extraHeader values. With --save-env, set-token also writes typed env GITHUB_ACCESS_TOKEN.

Interactive Mode

Recoverable missing parameters are handled through chatstyle:

  • Default mode: prompt automatically when a terminal is interactive and required values are missing.
  • CHATARCH_AUTO_PROMPT=0/false/no/off: disable default auto-prompting so machines/CI fail fast on missing inputs.
  • -i/--interactive: force prompting, even when CHATARCH_AUTO_PROMPT=off.
  • -I/--no-interactive: disable prompts and fail clearly when required values are missing.

Token inputs use password prompts and are not echoed.

Before creating a PR, reporting CI status, or preparing to merge, fetch the latest base:

git fetch origin main

Then confirm:

  • chatgh pr view / chatgh pr checks do not show mergeable=False or mergeable_state=dirty.
  • You have locally merged or rebased against the latest base and run the most relevant tests on that result.
  • Poll chatgh pr checks from the surrounding workflow when you need a terminal CI result; do not rely on a one-shot snapshot.

Python API

from chatgh.github.client import GitHubClient

client = GitHubClient(user_name="octocat", token="ghp_...")
prs = client.get_pull_requests("Hello-World")
view = client.get_pr_view("octocat/Hello-World", 1)
checks = client.get_pr_checks("octocat/Hello-World", 1)

Lower-level modules are also available:

  • chatgh.github.api: token, repository inference, git credential, and REST request helpers.
  • chatgh.github.commands: workflow functions used by the CLI.
  • chatgh.github.requests: PR/checks/actions payload construction.
  • chatgh.github.render: human-readable output, merge blockers, and tail helpers.

Relationship With ChatTool

The long-term chattool gh implementation has moved to chatgh. ChatTool may keep a thin wrapper for compatibility, but it should not maintain a forked GitHub implementation. ChatTool helpers that need GitHub token/remote logic should import chatgh.github.api.

Development Reference

When extending chatgh, start from the project interface guides: docs/interface-tree.en.md, docs/gh-interface-alignment.en.md, docs/agent-definition.en.md, and docs/agent-task-bot-alignment.en.md. For common GitHub capabilities, first inspect the official GitHub CLI gh command shape and help text. If gh already has the capability, prefer compatible names, positional arguments, and common aliases, then implement it through ChatGH's own auth, JSON, safety gates, and Python API. If gh does not have it, design a ChatGH-native surface. Official gh is reference-only; it is not a runtime dependency, CI/ops fallback, or real operation path. Agent/bot work must clearly distinguish GitHub-hosted Copilot/CAPI agent tasks from ChatGH self-hosted event-to-runner bridges.

Also consult official API documentation:

  • GitHub REST API: https://docs.github.com/en/rest
  • Pull requests API: https://docs.github.com/en/rest/pulls/pulls
  • Check runs API: https://docs.github.com/en/rest/checks/runs
  • Workflow runs API: https://docs.github.com/en/rest/actions/workflow-runs
  • Workflow jobs API: https://docs.github.com/en/rest/actions/workflow-jobs
  • Commit statuses API: https://docs.github.com/en/rest/commits/statuses
  • PyGithub: https://pygithub.readthedocs.io/

Local validation:

python -m pytest -q
python -m build
mkdocs build --strict

Default tests use mock/fake payloads and temporary paths. They do not call the live GitHub API or write real git credentials or env config.