| 1 | --- |
| 2 | title: The g1t CLI |
| 3 | description: Install the g1t command line, sign in, and work with repositories, issues, pull requests, runs, workflows, deployments, secrets and logs from a terminal, a script or an agent. |
| 4 | --- |
| 5 | |
| 6 | `g1t` is the command line for g1t. It does the work you would otherwise do on |
| 7 | the site: open and review pull requests, wait on checks, read a failing run's |
| 8 | logs, set secrets, read a project's logs, and call any operation of the |
| 9 | [API](/reference/api/). It is one file with nothing to install alongside it, |
| 10 | and it is built to be run by agents as much as by people: every command can |
| 11 | print JSON, nothing waits for input unless a person is at the terminal, and |
| 12 | exit codes say what happened. |
| 13 | |
| 14 | ```sh |
| 15 | g1t issue list --label bug |
| 16 | g1t pr create --fill |
| 17 | g1t pr checks --watch --fail-fast |
| 18 | g1t run logs --failed |
| 19 | ``` |
| 20 | |
| 21 | Every command and flag is listed in the [command reference](/reference/cli/). |
| 22 | |
| 23 | ## Install |
| 24 | |
| 25 | On Linux or macOS: |
| 26 | |
| 27 | ```sh |
| 28 | curl -fsSL https://g1t.sh/install | sh |
| 29 | ``` |
| 30 | |
| 31 | On Windows, in PowerShell: |
| 32 | |
| 33 | ```powershell |
| 34 | irm https://g1t.sh/install.ps1 | iex |
| 35 | ``` |
| 36 | |
| 37 | The script picks the build for your system, checks it against the |
| 38 | release's `SHA256SUMS`, and puts `g1t` in `~/.local/bin` (Windows: |
| 39 | `%LOCALAPPDATA%\g1t\bin`, which it adds to your `PATH`). Set |
| 40 | `G1T_INSTALL_DIR` to put it elsewhere, or `G1T_VERSION` to install a |
| 41 | version other than the latest. |
| 42 | |
| 43 | ### Upgrade |
| 44 | |
| 45 | From 0.3.4 on, `g1t upgrade` updates g1t to the newest release: |
| 46 | |
| 47 | ```sh |
| 48 | g1t upgrade # download and install the newest release |
| 49 | g1t upgrade --check # only say whether there is one |
| 50 | ``` |
| 51 | |
| 52 | It reads the newest release's manifest, `latest.json`, and checks its |
| 53 | signature (`latest.json.sig`) against g1t's release key, which is built |
| 54 | into every release. It then downloads the build for your system, checks |
| 55 | its SHA-256 against the manifest, and puts it where the running `g1t` is. |
| 56 | If anything does not check out, nothing changes. Releases come from |
| 57 | `https://g1t.sh/downloads/cli`, or from `G1T_DOWNLOAD_URL` if you set it. |
| 58 | |
| 59 | In a terminal, g1t looks for a newer release about once a day, in the |
| 60 | background, and says so after a command when there is one. It never looks |
| 61 | in CI or when its output is not a terminal. Set `G1T_NO_UPDATE_NOTIFIER=1` |
| 62 | to turn it off. |
| 63 | |
| 64 | A g1t built from source has no release key and cannot upgrade itself. |
| 65 | Neither can versions before 0.3.4. Update those by running the install |
| 66 | script again. |
| 67 | |
| 68 | ### Without the script |
| 69 | |
| 70 | Each release is a single file per platform, at |
| 71 | `https://g1t.sh/downloads/cli/latest/`: |
| 72 | |
| 73 | | Platform | File | |
| 74 | | --- | --- | |
| 75 | | Linux, x64 | `g1t-linux-x64` | |
| 76 | | Linux, ARM | `g1t-linux-arm64` | |
| 77 | | macOS, Apple silicon | `g1t-macos-arm64` | |
| 78 | | macOS, Intel | `g1t-macos-x64` | |
| 79 | | Windows, x64 | `g1t-windows-x64.exe` | |
| 80 | |
| 81 | ```sh |
| 82 | curl -fsSLo g1t https://g1t.sh/downloads/cli/latest/g1t-linux-x64 |
| 83 | chmod +x g1t && mv g1t ~/.local/bin/ |
| 84 | ``` |
| 85 | |
| 86 | Check a download against `https://g1t.sh/downloads/cli/latest/SHA256SUMS`. |
| 87 | `latest.json` beside it names the version and each file's SHA-256, and |
| 88 | `latest.json.sig` is its signature. A given version's files are at |
| 89 | `/downloads/cli/<version>/` and never change. |
| 90 | |
| 91 | To build it from source, with [Rust](https://www.rust-lang.org/tools/install): |
| 92 | |
| 93 | ```sh |
| 94 | git clone https://g1t.sh/flagon-io/g1t |
| 95 | cargo install --path g1t/crates/g1t |
| 96 | ``` |
| 97 | |
| 98 | `g1t --version` prints the version you have. |
| 99 | |
| 100 | ## Sign in |
| 101 | |
| 102 | ```sh |
| 103 | g1t auth login |
| 104 | ``` |
| 105 | |
| 106 | `g1t` shows a one-time code and opens your browser at |
| 107 | [g1t.sh/device](https://g1t.sh/device). Sign in there if you are not |
| 108 | already, check the code matches, and approve. The command finishes on its |
| 109 | own once you have. Where there is no browser (a server, a container, a |
| 110 | remote shell), it prints the link instead: open it on any device. |
| 111 | |
| 112 | To use an [access token](/guides/authentication/#access-tokens) you already |
| 113 | have, pipe it in: |
| 114 | |
| 115 | ```sh |
| 116 | g1t auth login --with-token < token.txt |
| 117 | ``` |
| 118 | |
| 119 | The token is kept in your system's credential store: the Keychain on |
| 120 | macOS, Credential Manager on Windows, the Secret Service on Linux. Where |
| 121 | there is none, as on most servers, it goes in the [config |
| 122 | file](#settings-and-environment), readable only by you; `--insecure-storage` |
| 123 | puts it there on purpose. |
| 124 | |
| 125 | | Command | What it does | |
| 126 | | --- | --- | |
| 127 | | `g1t auth status` | Each account you are signed in as, on each host, whether its token still works, and its scopes. Exits `4` when the active account's token does not work. | |
| 128 | | `g1t auth token` | Prints the token in use, for another program. | |
| 129 | | `g1t auth logout` | Forgets an account's token. | |
| 130 | | `g1t auth switch` | Makes another signed-in account on the same host the active one. | |
| 131 | |
| 132 | ### G1T_TOKEN |
| 133 | |
| 134 | When `G1T_TOKEN` is set, every command uses it instead of a stored token. |
| 135 | This is how to give `g1t` a token in containers, in agents' sandboxes, and |
| 136 | in [workflows](/guides/actions/), where the job's own token is |
| 137 | `secrets.G1T_TOKEN`: |
| 138 | |
| 139 | ```yaml |
| 140 | - run: g1t pr comment ${{ github.event.pull_request.number }} -b "Preview is up." |
| 141 | env: |
| 142 | G1T_TOKEN: ${{ secrets.G1T_TOKEN }} |
| 143 | ``` |
| 144 | |
| 145 | ### Self-hosted g1t |
| 146 | |
| 147 | `g1t` works with any g1t, not only g1t.sh. Sign in to yours with its |
| 148 | address: |
| 149 | |
| 150 | ```sh |
| 151 | g1t auth login --hostname git.example.com |
| 152 | ``` |
| 153 | |
| 154 | `g1t` asks it where its API is (its `/.well-known/g1t.json`), and remembers. |
| 155 | After that, commands in a clone of one of its repositories talk to it on |
| 156 | their own. Elsewhere, name it with `--hostname` or `G1T_HOST`; the first host |
| 157 | you sign in to is the default. You can be signed in to several hosts, and |
| 158 | as several accounts on each. |
| 159 | |
| 160 | ## Use it with git |
| 161 | |
| 162 | ```sh |
| 163 | g1t auth setup-git |
| 164 | ``` |
| 165 | |
| 166 | This makes `g1t` git's credential helper for each host you are signed in |
| 167 | to, so `git push`, `git fetch` and `git clone` over HTTPS use the same |
| 168 | token, with nothing more to type. It changes your global git config only for |
| 169 | those hosts' addresses (`credential.https://g1t.sh.helper`). `g1t auth login |
| 170 | --git` does both at once. To see the config lines without changing anything, |
| 171 | add `--dry-run`. |
| 172 | |
| 173 | [`g1t push`](/guides/containers/#push-large-layers-with-g1t-push), which sends container |
| 174 | images to g1t's registry, uses the same signed-in token. |
| 175 | |
| 176 | ## Which repository |
| 177 | |
| 178 | Commands about a repository work on the one the current directory is a |
| 179 | clone of, found from its git remotes: `upstream` if it is on g1t, then |
| 180 | `origin`, then the first one that is. In a pull request's own [working |
| 181 | copy](/guides/pull-requests/), they work on the repository the pull request |
| 182 | is for. |
| 183 | |
| 184 | Anywhere else, or to choose another, pass `--repo` (`-R`), or set |
| 185 | `G1T_REPO`: |
| 186 | |
| 187 | ```sh |
| 188 | g1t issue list -R acme/web |
| 189 | g1t pr view 14 -R git.example.com/acme/web |
| 190 | ``` |
| 191 | |
| 192 | ## Everyday work |
| 193 | |
| 194 | ### Issues |
| 195 | |
| 196 | ```sh |
| 197 | g1t issue list # open issues, newest first |
| 198 | g1t issue list --label bug --assignee @me |
| 199 | g1t issue view 12 --comments |
| 200 | g1t issue create -t "Greeting should name the caller" -b "Take a name from the first argument." |
| 201 | g1t issue comment 12 -b "Fixed in #14." |
| 202 | g1t issue edit 12 --add-label p1 --add-assignee @me |
| 203 | g1t issue close 12 --reason not_planned |
| 204 | ``` |
| 205 | |
| 206 | `@me` is you. At a terminal, `g1t issue create` without `--title` asks for |
| 207 | one and opens your editor for the body. |
| 208 | |
| 209 | ### Pull requests |
| 210 | |
| 211 | From a branch with your commits on it: |
| 212 | |
| 213 | ```sh |
| 214 | git switch -c greet-by-name |
| 215 | # ...commit... |
| 216 | g1t pr create --fill --issue 12 |
| 217 | ``` |
| 218 | |
| 219 | `g1t pr create` pushes the branch, then opens the pull request into the |
| 220 | default branch (`--base` for another). `--fill` takes the title and body from |
| 221 | the branch's commits; `--issue` says which issue it is for; `--draft` opens |
| 222 | it as a draft. |
| 223 | |
| 224 | To start a pull request for an issue without a branch of your own, as g1t's |
| 225 | agents do, run it with `--issue` from the default branch. g1t opens a draft |
| 226 | with a [working copy](/guides/pull-requests/) of its own and prints the |
| 227 | copy's git remote. Push your commits there, then mark it ready with a |
| 228 | summary of what changed and why: |
| 229 | |
| 230 | ```sh |
| 231 | g1t pr create --issue 12 |
| 232 | git push https://g1t.sh/pulls/pr_….git HEAD:main |
| 233 | g1t pr ready --summary "Reads a name from the first argument." |
| 234 | ``` |
| 235 | |
| 236 | Then, for any pull request: |
| 237 | |
| 238 | ```sh |
| 239 | g1t pr list |
| 240 | g1t pr view 14 # the current branch's when left out |
| 241 | g1t pr diff 14 |
| 242 | g1t pr checkout 14 # check its head out locally |
| 243 | g1t pr checks 14 --watch |
| 244 | g1t pr review 14 --approve -b "Reads well." |
| 245 | g1t pr review 14 --request-changes -b "Trim the name first." |
| 246 | g1t pr merge 14 --delete-branch |
| 247 | ``` |
| 248 | |
| 249 | `g1t pr merge` merges the way the repository is set to, once |
| 250 | [required checks](/guides/checks/) pass and [rules](/guides/rules/) allow; |
| 251 | `--admin` merges past them, with the Admin role. |
| 252 | |
| 253 | ### Checks and runs |
| 254 | |
| 255 | `g1t pr checks` lists a pull request's checks: g1t Actions jobs, check runs |
| 256 | and commit statuses. With `--watch` it waits until they have all finished, |
| 257 | redrawing at a terminal and printing a line per change when piped. |
| 258 | `--fail-fast` stops at the first failure instead of waiting for the rest. It |
| 259 | exits `0` when every check passed, `1` when one failed, and, without |
| 260 | `--watch`, `8` while any are still running. |
| 261 | |
| 262 | ```sh |
| 263 | g1t run list --branch main |
| 264 | g1t run view # the current branch's latest run |
| 265 | g1t run watch run_01kpx7b3c6d9e2f5g8h1j4k7mr |
| 266 | g1t run logs --failed |
| 267 | g1t run rerun --failed |
| 268 | ``` |
| 269 | |
| 270 | A run is named by its id (`run_…`), its number, or its address; left out, |
| 271 | it is the current branch's latest. `g1t run logs --failed` prints only the |
| 272 | steps that failed, each with its last 60 lines (`-n` for more or fewer): |
| 273 | what you need to see why, without the rest of the log. `g1t run watch` |
| 274 | exits `1` if the run fails. |
| 275 | |
| 276 | ### Workflows |
| 277 | |
| 278 | `g1t workflow` works with the workflows in `.g1t/workflows`, as the |
| 279 | repository's **Actions** page does. |
| 280 | |
| 281 | ```sh |
| 282 | g1t workflow list # those turned on; --all for every one |
| 283 | g1t workflow view ci.yml # its triggers, inputs and latest runs |
| 284 | g1t workflow view release.yml --yaml --ref v1.4.0 |
| 285 | g1t workflow run release.yml -f channel=stable |
| 286 | g1t workflow disable Nightly |
| 287 | g1t workflow enable nightly.yml |
| 288 | ``` |
| 289 | |
| 290 | A workflow is named by its file name (`ci.yml`), its id (`wfl_…`) or its |
| 291 | name (`CI`, in any case). When more than one has that name, name it by its |
| 292 | file. Left out at a terminal, g1t asks which; in a script it is an error |
| 293 | that names what to pass. |
| 294 | |
| 295 | `g1t workflow run` runs a workflow that has `on: workflow_dispatch`, on the |
| 296 | default branch or the branch or tag `--ref` names, and prints its run's |
| 297 | address once the run is there, so `g1t run watch` can follow it. Give its |
| 298 | inputs with `-f key=value` (or `-F key=@file` to read a value from a file), |
| 299 | or as one JSON object on stdin with `--json`: |
| 300 | |
| 301 | ```sh |
| 302 | echo '{"channel":"stable","dry_run":true}' | g1t workflow run release.yml --json |
| 303 | ``` |
| 304 | |
| 305 | At a terminal with no inputs given, g1t asks for each, offering its |
| 306 | default. Only the inputs the workflow declares are taken, as on the |
| 307 | [Actions page](/guides/actions/#runs-and-logs). `g1t workflow view --yaml` |
| 308 | prints the workflow's file as it is on the default branch, or on `--ref`. |
| 309 | Turning a workflow off keeps its file: nothing starts it until it is |
| 310 | turned on again, and a workflow the workspace requires stays on. |
| 311 | |
| 312 | ### Deployments, logs and secrets |
| 313 | |
| 314 | ```sh |
| 315 | g1t deploy list --env production |
| 316 | g1t deploy view dep_01kq8m3t5v7x9z1b3d5f7h9k2m |
| 317 | |
| 318 | g1t logs --since 1h --level error,fatal |
| 319 | g1t logs -q '"payment failed"' --follow |
| 320 | g1t logs --errors --state open |
| 321 | |
| 322 | g1t secret list |
| 323 | echo "$NPM_TOKEN" | g1t secret set NPM_TOKEN |
| 324 | g1t secret set STRIPE_KEY --env production < stripe-key.txt |
| 325 | g1t secret set NPM_TOKEN --brokered-host registry.npmjs.org < npm-token.txt |
| 326 | g1t secret delete STRIPE_KEY --env preview |
| 327 | g1t secret list --workspace acme |
| 328 | ``` |
| 329 | |
| 330 | `g1t logs` reads the [observability](/guides/observability/) data of the |
| 331 | current repository's project, or of `--project WORKSPACE/SLUG`. A secret's |
| 332 | value is read from stdin, so it stays out of your shell's history; at a |
| 333 | terminal with nothing piped, `g1t` asks for it without echoing. Values are |
| 334 | never printed. `--brokered-host` makes it a [brokered |
| 335 | secret](/guides/secrets-and-variables/#brokered-secrets). |
| 336 | |
| 337 | ### What needs you |
| 338 | |
| 339 | ```sh |
| 340 | g1t status |
| 341 | ``` |
| 342 | |
| 343 | Your open pull requests and their checks, reviews asked of you, what is |
| 344 | assigned to you, and failing checks, across every repository you can see. |
| 345 | Inside a working copy it also lists your active sessions and claims in that |
| 346 | repository. |
| 347 | |
| 348 | ## Coordinating work |
| 349 | |
| 350 | When several people and agents work in one repository, `g1t session` and |
| 351 | `g1t work` say who is on what, so nobody starts work that is already under |
| 352 | way and everyone hears what changes under them. Claims are advisory: a |
| 353 | claim never stops anyone, it tells them. |
| 354 | |
| 355 | ### Sessions |
| 356 | |
| 357 | A session is one run of an agent's harness, such as one Claude Code |
| 358 | session. Starting one remembers it for the working copy, and the commands |
| 359 | after it use it: |
| 360 | |
| 361 | ```sh |
| 362 | g1t session start --harness claude-code --issue 12 |
| 363 | g1t session log "Split the parser before touching the lexer." |
| 364 | g1t session attach --pull 14 --head-commit "$(git rev-parse HEAD)" |
| 365 | g1t session heartbeat |
| 366 | g1t session end --reason done |
| 367 | ``` |
| 368 | |
| 369 | | Command | What it does | |
| 370 | | --- | --- | |
| 371 | | `g1t session start` | Starts a session and prints its id. `--harness` (`claude_code`, `codex`, `cursor`, `copilot` or `other`; `claude-code` works too; `claude_managed_agents` is only for the sessions g1t starts itself, with `g1t work dispatch`), `--harness-session-id`, `--issue`, `--pull`, `--branch` (the current one by default) and `--title`. Starting again with the same `--harness-session-id` returns the same session. For a subagent, `--parent` (the session that started it), `--agent-type`, `--task`, `--prompt` and `--model`; a subagent's session is not kept as the working copy's (nor is one with `--no-remember`). | |
| 372 | | `g1t session heartbeat` | Says the session is still working, and renews its claims. A session with no heartbeat for 15 minutes reads as idle, and after 2 hours as ended. | |
| 373 | | `g1t session log TEXT` | Records a note. `--kind` takes `note`, `prompt`, `message`, `tool_call` (or `tool-call`) or `skill` (a skill's name), `--tool` names the tool, and `--key` makes recording the same entry twice do nothing. `-` reads the text from stdin; put `--` before text that starts with a dash. | |
| 374 | | `g1t session attach` | Points the session at an `--issue`, a `--pull`, a `--branch` or its latest `--head-commit`, or gives it a `--title`: what it is for, which replaces the title it had. | |
| 375 | | `g1t session touch` | Says what the session touched: `--file PATH`, `--commit SHA`, `--branch NAME`, `--pull N` (one it opened), `--issue N`, each repeatable. Ties the session to the pull requests and issues they lead to; a file another active session touched too is an `overlap.detected` for both. | |
| 376 | | `g1t session updates [ID]` | What other sessions did that concerns this one (claims, overlaps, dependency changes, decisions, merge queue results), oldest first, up to 100. Reading never clears them. It first says which files the working copy changed, so overlapping edits are noticed (`G1T_TOUCH=0` turns that off). | |
| 377 | | `g1t session acknowledge ID... --note TEXT` | Records your decision about those updates (what changes in your plan, or why nothing does) and clears exactly the IDs given, for this session only; `--session` names another of yours. Saying the same again does nothing. | |
| 378 | | `g1t session end` | Ends it, with an optional `--reason` and `--result` (what it reported; `-` reads it from stdin), and forgets it. Its subagents still going end with it. | |
| 379 | | `g1t session list` | The repository's sessions; `--state active`, `--issue`, `--pull` (any session tied to it), `--path` (those that touched a file, or a folder ending in `/`), `--subagents` to list subagents under the sessions that started them. | |
| 380 | | `g1t session view [ID]` | A session and what it recorded, its subagents and their results, the issues and pull requests it worked on, and the skills used; the current one without an id. | |
| 381 | |
| 382 | The id is kept in `.git/g1t/session`, in the working copy's own git |
| 383 | directory, so each worktree has its own. `G1T_SESSION` overrides it, for |
| 384 | a harness that runs several sessions in one working copy. |
| 385 | |
| 386 | ### Claims and context |
| 387 | |
| 388 | ```sh |
| 389 | g1t work context 12 # everything about #12's work |
| 390 | g1t work claim 12 --note "Taking the parser" --ttl 1h |
| 391 | g1t work claim --title "Preview builds time out" --body "Over 1 GB, the build stops at 10 minutes." |
| 392 | g1t work release 12 --reason done |
| 393 | g1t work handoff 12 --to ana --note "Parser done; lexer tests still fail." |
| 394 | g1t work list # active claims and sessions here |
| 395 | ``` |
| 396 | |
| 397 | `g1t work context` is the one call to make before starting: the issue and |
| 398 | its definition of done, who has claimed it, its sessions, its pull |
| 399 | requests with their checks, overlaps and place in the merge queue, what it |
| 400 | waits on and what waits on it, its decisions, its last integration failure |
| 401 | and its recent events. |
| 402 | |
| 403 | `g1t work claim` says you are working on an issue. It lasts 30 minutes |
| 404 | unless `--ttl` says otherwise (at most `4h`), and a heartbeat of the session |
| 405 | it was made in renews it. It is made in the current session, if there is |
| 406 | one. If others have claimed the issue too, or it waits on issues that are |
| 407 | not done, the answer says so. `g1t work handoff` ends your claim and asks |
| 408 | `--to` someone, or anyone without it, to take the issue over, with a |
| 409 | `--note` saying where it stands. Claims, releases and hand-offs are the |
| 410 | current session's, so two sessions of yours (sibling subagents) each hold |
| 411 | their own. |
| 412 | |
| 413 | For work that has no issue yet, `g1t work claim --title "…"` (with |
| 414 | `--body` for its description) opens the issue and claims it in one step, |
| 415 | and attaches the current session to it; it prints the new issue's number. |
| 416 | Use it once the work is a change others should know about, after looking |
| 417 | for an issue that already covers it; questions, exploration and trivial |
| 418 | fixes need none. A number and `--title` together are refused. |
| 419 | |
| 420 | ### Starting a session on an issue |
| 421 | |
| 422 | ```sh |
| 423 | g1t work dispatch 12 # on the workspace's Anthropic account |
| 424 | g1t work dispatch 12 --mode plan --instruction "Keep the old flag" |
| 425 | g1t work dispatch --title "Add a healthcheck" --handoff # open the issue; print a claude command |
| 426 | ``` |
| 427 | |
| 428 | `g1t work dispatch` starts work on an issue in a session on your own |
| 429 | Claude: with the workspace's Anthropic [AI provider](/guides/ai/), a Claude Managed Agents |
| 430 | session on that account (it prints the session's page on g1t); without |
| 431 | one, or with `--handoff`, the `claude` command line to run in your working |
| 432 | copy with g1t's [Claude Code plugin](/guides/claude-code-plugin/). |
| 433 | `--managed` fails rather than hand off. `--mode` is `plan`, `implement` or |
| 434 | `review`. See [Start a session on your Anthropic account](/guides/sessions/#start-a-session-on-your-anthropic-account). |
| 435 | |
| 436 | ### Dependencies |
| 437 | |
| 438 | ```sh |
| 439 | g1t work block 12 --by 9 --by 10 # #12 waits on #9 and #10 |
| 440 | g1t work unblock 12 --by 9 |
| 441 | ``` |
| 442 | |
| 443 | These change the issue's `blocked_by` through `update_issue`. An issue |
| 444 | cannot wait on itself, and g1t refuses a cycle. |
| 445 | |
| 446 | ### Following events |
| 447 | |
| 448 | `g1t work events` prints the repository's recent events, oldest first. |
| 449 | With `--follow` it keeps printing them as they happen, without a webhook or |
| 450 | a public address, until you stop it with Ctrl-C: |
| 451 | |
| 452 | ```sh |
| 453 | g1t work events --follow --issue 12 |
| 454 | g1t work events --follow --type integration.failed --type overlap.detected --json |
| 455 | ``` |
| 456 | |
| 457 | | Flag | | |
| 458 | | --- | --- | |
| 459 | | `--type`, `-t` | Only events of this type, such as `work.claimed`; repeat for more. | |
| 460 | | `--issue`, `-i` | Only events about this issue or pull request; repeat for more. | |
| 461 | | `--since`, `-s` | Only events since then: `15m`, `2h`, `1d`, or an RFC 3339 time. | |
| 462 | | `--after` | Start after this event id, to resume where an earlier follow stopped. | |
| 463 | | `--limit`, `-L` | How many past events to show first; 20 by default. | |
| 464 | |
| 465 | Each event is one line: its time, type, issue or pull request, a summary |
| 466 | and its id. With `--json`, each is one compact JSON object on a line of its |
| 467 | own, so a program can read them as they come. Following asks |
| 468 | [`list_events`](/reference/api/repositories/list-events/) with `after` and |
| 469 | `wait`, so the server holds each request until something happens; when a |
| 470 | call fails, `g1t` waits (1 second, then longer, up to 30) and resumes from |
| 471 | the last event it printed. A refused token stops it with exit code `4`. |
| 472 | |
| 473 | ### Why a line is as it is |
| 474 | |
| 475 | ```sh |
| 476 | g1t why src/parser.rs:120 |
| 477 | g1t why src/parser.rs --ref main |
| 478 | ``` |
| 479 | |
| 480 | `g1t why` follows a line to the commit that last changed it, the pull |
| 481 | request that merged that commit, the issue the pull request was for, and |
| 482 | the decisions and sessions recorded on them. A path is read from where you |
| 483 | are in the working copy. |
| 484 | |
| 485 | ### In an agent's hooks |
| 486 | |
| 487 | These commands are made to be run by a harness's hooks in the background: |
| 488 | they never ask anything, they fail at once with exit code `4` when there is |
| 489 | no token, and they give up on a call after 15 seconds. Against a g1t server |
| 490 | older than the CLI, a command it cannot do yet fails saying so. |
| 491 | |
| 492 | ## Scripting with JSON |
| 493 | |
| 494 | Every command takes `--json`. Alone, it prints every field the API returns; |
| 495 | with a comma-separated list, only those (`g1t workflow run` is the one |
| 496 | exception: there, `--json` alone reads the inputs from stdin): |
| 497 | |
| 498 | ```sh |
| 499 | g1t pr list --json number,title,check_status |
| 500 | ``` |
| 501 | |
| 502 | ```json |
| 503 | [{"check_status":"passed","number":14,"title":"Greeting should name the caller"}] |
| 504 | ``` |
| 505 | |
| 506 | The fields are the API's own, named as in the [API reference](/reference/api/) |
| 507 | and always `snake_case`. A field that does not exist is an error that lists |
| 508 | the ones that do. Piped, JSON is one compact line with its keys in a fixed |
| 509 | order, so the same input gives the same output; at a terminal it is |
| 510 | indented. |
| 511 | |
| 512 | `--jq` runs a [jq](https://jqlang.org/manual/) expression over the JSON, |
| 513 | with nothing else to install. Strings come out bare, everything else as |
| 514 | JSON: |
| 515 | |
| 516 | ```sh |
| 517 | g1t pr list --jq '.[] | select(.check_status == "failed") | .number' |
| 518 | g1t run list --jq '.[] | [.id, .conclusion] | @tsv' |
| 519 | ``` |
| 520 | |
| 521 | Without `--json`, output piped to another program is one record per line, |
| 522 | fields separated by tabs, with no header and no color, ready for `cut`, |
| 523 | `awk` or `while read`. Lists show 20 entries unless `--limit` (`-L`) says |
| 524 | otherwise. |
| 525 | |
| 526 | ### Exit codes |
| 527 | |
| 528 | | Code | Meaning | |
| 529 | | --- | --- | |
| 530 | | `0` | It worked. | |
| 531 | | `1` | It failed: the API refused it, the network failed, checks or a run failed. | |
| 532 | | `2` | The command was used wrongly: an unknown flag, a missing argument, a JSON field that does not exist. | |
| 533 | | `4` | Signing in is needed, or the token was refused. | |
| 534 | | `8` | Checks are still running (`g1t pr checks` without `--watch`). | |
| 535 | |
| 536 | An error is one line on stderr, starting `g1t:`. When a token lacks a |
| 537 | [scope](/guides/authentication/#scopes) the call needs, the line names it. |
| 538 | |
| 539 | ### No questions when piped |
| 540 | |
| 541 | `g1t` asks for a missing title, opens an editor for a body, or offers a |
| 542 | choice only when stdin and stderr are both a terminal. Anywhere else, and |
| 543 | whenever `G1T_PROMPT_DISABLED` is set, a command missing something fails at |
| 544 | once with exit code `2` and names the flag that supplies it. |
| 545 | |
| 546 | ## Call any operation |
| 547 | |
| 548 | `g1t api` calls any operation of the [API](/reference/api/) by its name, |
| 549 | with your token, and fills the repository in from where you are: |
| 550 | |
| 551 | ```sh |
| 552 | g1t api list_issues -f state=closed --jq '.[].title' |
| 553 | g1t api create_label -f name=p1 -f color=d73a4a |
| 554 | g1t api get_workflow_run -f id=run_01kpx7b3c6d9e2f5g8h1j4k7mr |
| 555 | g1t api --list label # the operations about labels |
| 556 | ``` |
| 557 | |
| 558 | A path works too, with `{owner}`, `{name}` and `{workspace}` filled in: |
| 559 | |
| 560 | ```sh |
| 561 | g1t api /repos/{owner}/{name}/labels |
| 562 | g1t api user --jq .username |
| 563 | ``` |
| 564 | |
| 565 | `-f key=value` sends a string, `-F key=value` sends `true`, `false`, `null` |
| 566 | and numbers as JSON and `@file` as a file's contents, and `key[]=value` adds |
| 567 | to a list. Fields go in the query of a `GET` and in the JSON body otherwise. |
| 568 | `-X` sets the method, `-H` adds a header, and `--input file` sends a file as |
| 569 | the body. `--paginate` follows each next page, and with `--slurp` puts every |
| 570 | page's items in one array. A request the API refuses prints its error body |
| 571 | and exits `1`. |
| 572 | |
| 573 | In Git Bash on Windows, an argument starting with `/` is turned into a |
| 574 | Windows path before `g1t` sees it: leave the leading slash off |
| 575 | (`g1t api repos/{owner}/{name}`), or set `MSYS_NO_PATHCONV=1`. |
| 576 | |
| 577 | ## From agents and harnesses |
| 578 | |
| 579 | An agent with a shell, such as Claude Code, Codex or Cursor, can use `g1t` |
| 580 | the way you do. A command and its JSON cost an agent less of its context |
| 581 | than a set of tool definitions, and the agent finds what it needs with |
| 582 | `--help`. For clients without a shell, use the [MCP server](/reference/mcp/). |
| 583 | |
| 584 | 1. Install `g1t` where the agent runs, as [above](#install). |
| 585 | 2. Give it a token. Either sign in once with `g1t auth login` as the user |
| 586 | the agent runs as, or set `G1T_TOKEN` in its environment. Make a token |
| 587 | with only the [scopes](/guides/authentication/#scopes) it needs. |
| 588 | 3. Tell it `g1t` is there. A few lines in the project's `CLAUDE.md` or |
| 589 | `AGENTS.md` are enough: |
| 590 | |
| 591 | ```md |
| 592 | This repository is on g1t. Use the `g1t` CLI for issues, pull requests, |
| 593 | checks and runs; add `--json` to read results, and see `g1t <command> --help`. |
| 594 | |
| 595 | - Open a pull request: `g1t pr create --fill --issue <n>` |
| 596 | - Wait for checks: `g1t pr checks --watch --fail-fast` (exit 0 passed, 1 failed) |
| 597 | - See why a run failed: `g1t run logs --failed` |
| 598 | - Run a workflow by hand: `g1t workflow run <file> -f key=value` |
| 599 | - Anything else: `g1t api --list <word>`, then `g1t api <operation>` |
| 600 | ``` |
| 601 | |
| 602 | `g1t` never waits for input in an agent's shell, since its stdin is not a |
| 603 | terminal. Its JSON is compact and in a stable order, its lists are short |
| 604 | by default, and `g1t pr checks --watch --fail-fast` and `g1t run logs |
| 605 | --failed` give an agent the one thing it is waiting for, and no more. |
| 606 | |
| 607 | ## Aliases and completion |
| 608 | |
| 609 | An alias is a shortcut for a command you type often. `$1`, `$2`… take the |
| 610 | arguments after it, and the rest go on the end: |
| 611 | |
| 612 | ```sh |
| 613 | g1t alias set bugs 'issue list --label bug' |
| 614 | g1t alias set co 'pr checkout' |
| 615 | g1t alias set mine '!g1t pr list --author @me --json number,title' |
| 616 | g1t bugs --limit 5 |
| 617 | ``` |
| 618 | |
| 619 | An alias starting with `!` runs in `sh`. `g1t alias list` lists them, and |
| 620 | `g1t alias delete` removes one. |
| 621 | |
| 622 | `g1t completion <shell>` prints a completion script for `bash`, `zsh`, |
| 623 | `fish`, `powershell` or `elvish`: |
| 624 | |
| 625 | ```sh |
| 626 | g1t completion bash > ~/.local/share/bash-completion/completions/g1t |
| 627 | g1t completion zsh > "${fpath[1]}/_g1t" |
| 628 | g1t completion fish > ~/.config/fish/completions/g1t.fish |
| 629 | g1t completion powershell >> $PROFILE |
| 630 | ``` |
| 631 | |
| 632 | ## Settings and environment |
| 633 | |
| 634 | `g1t` keeps the hosts you are signed in to, their accounts and your aliases |
| 635 | in `config.json`, in `~/.config/g1t` (`%APPDATA%\g1t` on Windows; |
| 636 | `$XDG_CONFIG_HOME/g1t` when that is set). |
| 637 | |
| 638 | | Variable | | |
| 639 | | --- | --- | |
| 640 | | `G1T_TOKEN` | A token to use instead of the stored one. | |
| 641 | | `G1T_HOST` | The host to use when no repository names one. | |
| 642 | | `G1T_REPO` | The repository, as `[HOST/]OWNER/NAME`. | |
| 643 | | `G1T_CONFIG_DIR` | Where to keep `config.json`. | |
| 644 | | `G1T_KEYRING` | `off` keeps tokens out of the system's credential store. | |
| 645 | | `G1T_PROMPT_DISABLED` | Never ask anything. | |
| 646 | | `G1T_EDITOR`, `VISUAL`, `EDITOR` | The editor for bodies and summaries. | |
| 647 | | `G1T_BROWSER`, `BROWSER` | The browser `--web` and `g1t browse` open. | |
| 648 | | `NO_COLOR` | Plain output at a terminal too. | |
| 649 | | `G1T_DEBUG` | Print each request's method, address and status on stderr. | |