CLI commands

Every command of the g1t CLI, with its arguments and flags. g1t <command> --help prints the same at a terminal. Each command that talks to the API names the operations it calls, which link to the API reference; g1t api calls any other.

Flags every command takes

Flag
-R, --repo <[HOST/]OWNER/NAME>	The repository, as [HOST/]OWNER/NAME, instead of the current directory’s.
--hostname <HOST>	The g1t host, such as g1t.sh or git.example.com.
--json [FIELDS]	Print JSON: every field, or only the comma-separated FIELDS.
--jq <EXPRESSION>	Run a jq expression over the JSON and print what it gives.

g1t auth

Sign in, sign out, and set git up to use g1t’s credentials.

g1t auth login

Sign in to a g1t host.

g1t auth login [OPTIONS]

Argument or flag
--with-token	Read a token from stdin instead of approving in the browser.
--insecure-storage	Keep the token in the config file, not the system keychain.
--no-browser	Do not open the browser; just print the link.
--git	Also set git up to use g1t’s credentials (see g1t auth setup-git).

Without --with-token, g1t shows a code and a link; approve it in the browser, signed in.
With --with-token, the token is read from stdin:
  g1t auth login --with-token < token.txt

Calls device_code, device_token, whoami.

g1t auth logout

Sign out of an account on a host.

g1t auth logout [OPTIONS]

Argument or flag
-u, --user <USER>	The account, when more than one is signed in on the host.

g1t auth status

Show which accounts are signed in, and whether their tokens work.

g1t auth status [OPTIONS]

Argument or flag
--show-token	Print each token too.

Calls whoami.

g1t auth token

Print the token in use, for another program.

g1t auth token [OPTIONS]

Argument or flag
-u, --user <USER>	The account, when more than one is signed in on the host.

g1t auth switch

Make another signed-in account on a host the active one.

g1t auth switch [OPTIONS]

Argument or flag
-u, --user <USER>	The account, when more than one is signed in on the host.

g1t auth setup-git

Make git use g1t’s credentials for pushing and fetching over HTTPS.

g1t auth setup-git [OPTIONS]

Argument or flag
--dry-run	Print the git config commands instead of running them.

g1t repo

Repositories: view, clone, create, list.

g1t repo view

Show a repository.

g1t repo view [OPTIONS] [REPOSITORY]

Argument or flag
[REPOSITORY]	OWNER/NAME; the current repository when left out.
-w, --web	Open it in the browser.

Calls get_repo.

g1t repo clone

Clone a repository.

g1t repo clone [OPTIONS] <REPOSITORY> [DIRECTORY] [-- <GIT_FLAGS>...]

Argument or flag
<REPOSITORY>	OWNER/NAME, or NAME for one of your own.
[DIRECTORY]	Where to clone it.
[GIT_FLAGS]	After --. Flags for git clone, after –.

Calls whoami.

g1t repo create

Make a repository.

g1t repo create [OPTIONS] [NAME]

Argument or flag
[NAME]	NAME, or WORKSPACE/NAME.
--public	Anyone can see it. Repositories are private unless this is given.
--private	Only people with a role on it can see it (the default).
-d, --description <DESCRIPTION>
-c, --clone	Clone it once it is made.
--source <DIR>	Add it as a remote of this directory’s repository and push it there.
--remote <REMOTE>	The remote’s name, with –source. Default: origin.

Calls create_repo.

g1t repo list

List repositories you can see.

g1t repo list [OPTIONS] [WORKSPACE]

Argument or flag
[WORKSPACE]	Only this workspace’s.
-q, --query <QUERY>	Only those whose name or description holds this.
-L, --limit <LIMIT>	Default: 20.

Calls list_repos.

g1t issue

Issues: list, view, create, comment, close, reopen, edit.

g1t issue list

List issues.

g1t issue list [OPTIONS]

Argument or flag
-s, --state <STATE>	One of open, closed, all. Default: open.
-l, --label <LABEL>	Only issues with this label.
-m, --milestone <MILESTONE>	Only issues in the milestone of this number.
-a, --assignee <ASSIGNEE>	Only issues assigned to this person (@me for you).
-A, --author <AUTHOR>	Only issues opened by this person (@me for you).
-L, --limit <LIMIT>	Default: 20.

Calls list_issues.

g1t issue view

Show an issue, with its comments.

g1t issue view [OPTIONS] <NUMBER>

Argument or flag
<NUMBER>	The issue’s number.
-c, --comments	Show its comments too.
-w, --web	Open it in the browser.

Calls get_issue.

g1t issue create

Open an issue.

g1t issue create [OPTIONS]

Argument or flag
-t, --title <TITLE>
-b, --body <BODY>	The text. Markdown.
-F, --body-file <FILE>	Read the text from a file, or - for stdin.
-l, --label <LABEL>	A label; repeat for more.
-a, --assignee <ASSIGNEE>	Someone to assign; repeat for more (@me for you).
-m, --milestone <MILESTONE>	A milestone’s number.
-w, --web	Open the new-issue page in the browser instead.

Calls create_issue, update_issue.

g1t issue comment

Comment on an issue.

g1t issue comment [OPTIONS] [NUMBER]

Argument or flag
[NUMBER]	The number; for a pull request, the current branch’s when left out.
-b, --body <BODY>	The text. Markdown.
-F, --body-file <FILE>	Read the text from a file, or - for stdin.

Calls add_comment.

g1t issue close

Close an issue.

g1t issue close [OPTIONS] <NUMBER>

Argument or flag
<NUMBER>
-r, --reason <REASON>	One of completed, not_planned.
-c, --comment <COMMENT>	Leave a comment as it closes.

Calls close_issue, add_comment.

g1t issue reopen

Reopen an issue.

g1t issue reopen [OPTIONS] <NUMBER>

Argument or flag
<NUMBER>
-c, --comment <COMMENT>	Leave a comment as it reopens.

Calls reopen_issue, add_comment.

g1t issue edit

Change an issue’s title, body, labels, assignees or milestone.

g1t issue edit [OPTIONS] <NUMBER>

Argument or flag
<NUMBER>
-t, --title <TITLE>
-b, --body <BODY>	The text. Markdown.
-F, --body-file <FILE>	Read the text from a file, or - for stdin.
--add-label <LABEL>
--remove-label <LABEL>
--add-assignee <LOGIN>
--remove-assignee <LOGIN>
-m, --milestone <MILESTONE>	A milestone’s number.
--remove-milestone	Take it out of its milestone.

Calls update_issue, get_issue.

g1t pr

Pull requests: list, view, create, check out, diff, checks, review, merge.

g1t pr list

List pull requests.

g1t pr list [OPTIONS]

Argument or flag
-s, --state <STATE>	One of open, closed, merged, all. Default: open.
-B, --base <BASE>	Only those merging into this branch.
-l, --label <LABEL>
-A, --author <AUTHOR>	Only those opened by this person (@me for you).
-d, --draft	Only drafts.
-L, --limit <LIMIT>	Default: 20.

Calls list_pull_requests.

g1t pr view

Show a pull request.

g1t pr view [OPTIONS] [NUMBER]

Argument or flag
[NUMBER]	The number; the current branch’s when left out.
-c, --comments
-w, --web

Calls get_pull_request, list_pull_requests.

g1t pr create

Open a pull request from a branch, or start one for an issue.

g1t pr create [OPTIONS]

Argument or flag
-t, --title <TITLE>
-b, --body <BODY>	The text. Markdown.
-F, --body-file <FILE>	Read the text from a file, or - for stdin.
-B, --base <BASE>	The branch to merge into; the default branch when left out.
-H, --head <HEAD>	The branch with the changes; the current one when left out.
-i, --issue <ISSUE>	The issue it is for. Without a branch, starts a draft in a working copy of its own.
-f, --fill	Take the title and body from the branch’s commits.
-d, --draft	Open it as a draft.
--no-push	Do not push the branch first.

Calls create_pull_request, get_repo, convert_pull_request_to_draft.

g1t pr checkout

Check a pull request’s changes out locally.

g1t pr checkout [OPTIONS] <NUMBER>

Argument or flag
<NUMBER>
-b, --branch <BRANCH>	The local branch’s name; pr-NUMBER when left out.
-f, --force	Reset the local branch to the pull request’s head even if it has other commits.

Calls get_pull_request.

g1t pr diff

Show a pull request’s changes as a diff.

g1t pr diff [OPTIONS] [NUMBER]

Argument or flag
[NUMBER]
--name-only	Only the changed files’ names.
--color <COLOR>	Color: auto, always or never. Default: auto.

Calls get_pull_request_changes.

g1t pr checks

Show a pull request’s checks; –watch waits for them.

g1t pr checks [OPTIONS] [NUMBER]

Argument or flag
[NUMBER]
-w, --watch	Wait until every check has finished.
--fail-fast	With –watch, stop at the first failing check.
-i, --interval <INTERVAL>	Seconds between looks, with –watch. Default: 10.

Calls get_pull_request, list_check_runs_for_ref, get_combined_status.

g1t pr review

Approve a pull request, or ask for changes.

g1t pr review [OPTIONS] <--approve|--request-changes|--comment> [NUMBER]

Argument or flag
[NUMBER]
-a, --approve
-r, --request-changes
-c, --comment	Comment without approving or asking for changes.
-b, --body <BODY>	The text. Markdown.
-F, --body-file <FILE>	Read the text from a file, or - for stdin.

Calls review_pull_request, add_comment.

g1t pr merge

Merge a pull request.

g1t pr merge [OPTIONS] [NUMBER]

Argument or flag
[NUMBER]
--keep-issue-open	Leave the issue it is for open.
--admin	Merge past failing required checks and rules (needs the Admin role).
-d, --delete-branch	Delete the local and remote branch afterwards.

Calls merge_pull_request, delete_branch.

g1t pr ready

Mark a draft ready for review, or turn it back into a draft.

g1t pr ready [OPTIONS] [NUMBER]

Argument or flag
[NUMBER]
-s, --summary <SUMMARY>	What changed and why; it becomes the description. The current one when left out.
--undo	Turn it back into a draft.

Calls mark_pull_request_ready, convert_pull_request_to_draft.

g1t pr comment

Comment on a pull request.

g1t pr comment [OPTIONS] [NUMBER]

Argument or flag
[NUMBER]	The number; for a pull request, the current branch’s when left out.
-b, --body <BODY>	The text. Markdown.
-F, --body-file <FILE>	Read the text from a file, or - for stdin.

Calls add_comment.

g1t pr close

Close a pull request without merging it.

g1t pr close [OPTIONS] [NUMBER]

Argument or flag
[NUMBER]	The number; the current branch’s when left out.

Calls close_pull_request.

g1t pr reopen

Reopen a closed pull request.

g1t pr reopen [OPTIONS] [NUMBER]

Argument or flag
[NUMBER]	The number; the current branch’s when left out.

Calls reopen_pull_request.

g1t run

Workflow runs: list, view, watch, logs, rerun, cancel.

g1t run list

List workflow runs, newest first.

g1t run list [OPTIONS]

Argument or flag
-w, --workflow <WORKFLOW>	Only this workflow’s: its file name or id.
-b, --branch <BRANCH>
-e, --event <EVENT>	Only runs for this event: push, pull_request, schedule…
-c, --commit <COMMIT>	Only runs of this commit.
--pr <PR>	Only runs for this pull request.
-L, --limit <LIMIT>	Default: 20.

Calls list_workflow_runs.

g1t run view

Show a run’s jobs and steps.

g1t run view [OPTIONS] [RUN]

Argument or flag
[RUN]
-j, --job <JOB>	Show this job’s steps only.
--log	Print the log too.
--log-failed	Print the failing steps’ logs too.
-w, --web
--exit-status	Exit 1 when the run failed.

Calls get_workflow_run, get_job_logs.

g1t run watch

Follow a run until it finishes; exits 1 if it fails.

g1t run watch [OPTIONS] [RUN]

Argument or flag
[RUN]
-i, --interval <INTERVAL>	Seconds between looks. Default: 3.

Calls get_workflow_run.

g1t run logs

Print a run’s logs; –failed prints only the failing steps’ tails.

g1t run logs [OPTIONS] [RUN]

Argument or flag
[RUN]
-j, --job <JOB>	Only this job’s (its id, key or name).
-f, --failed	Only the failing steps, and only their last lines.
-n, --tail <TAIL>	How many lines of each failing step to print, with –failed. Default: 60.

Calls get_workflow_run, get_job_logs.

g1t run rerun

Run a run again: all of it, its failed jobs, or one job.

g1t run rerun [OPTIONS] [RUN]

Argument or flag
[RUN]
--failed	Only the jobs that failed.
-j, --job <JOB>	Only this job (its id).
-d, --debug	With debug logging.

Calls rerun_workflow_run, rerun_failed_jobs, rerun_job.

g1t run cancel

Cancel a run.

g1t run cancel [OPTIONS] [RUN]

Argument or flag
[RUN]	The run’s id (run_…) or number; the current branch’s latest when left out.

Calls cancel_workflow_run.

g1t workflow

Workflows in .g1t/workflows: list, view, run, enable, disable.

g1t workflow list

List the workflows in .g1t/workflows, with whether each is on.

g1t workflow list [OPTIONS]

Argument or flag
-a, --all	Include the workflows that are turned off.
-L, --limit <LIMIT>	Default: 50.

Calls list_workflows.

g1t workflow view

Show a workflow and its latest runs; –yaml prints its file.

g1t workflow view [OPTIONS] [WORKFLOW]

Argument or flag
[WORKFLOW]	Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out.
-y, --yaml	Print the workflow’s file.
-g, --ref <REF>	The branch or tag to read the file on, with –yaml; the default branch when left out.
-w, --web	Open it in the browser.

Calls list_workflows, get_workflow, list_workflow_runs.

g1t workflow run

Run a workflow that has on: workflow_dispatch, and print its run’s address.

g1t workflow run [OPTIONS] [WORKFLOW]

Argument or flag
[WORKFLOW]	Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out.
-g, --ref <REF>	The branch or tag to run it on; the default branch when left out.
-f, --raw-field <KEY=VALUE>	An input, key=value; repeat for more.
-F, --field <KEY=VALUE>	An input, key=value, where @FILE reads the value from a file (@- from stdin).

Inputs are given with -f (or -F, where @FILE reads a file), or as a JSON object on
stdin with --json. At a terminal, with none given, g1t asks for each input.

Examples:
  g1t workflow run release.yml
  g1t workflow run release.yml --ref v1.4.0 -f channel=stable -f dry_run=true
  echo '{"channel":"stable"}' | g1t workflow run Release --json

Calls list_workflows, dispatch_workflow, list_workflow_runs.

g1t workflow enable

Turn a workflow on again.

g1t workflow enable [OPTIONS] [WORKFLOW]

Argument or flag
[WORKFLOW]	Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out.

Calls list_workflows, enable_workflow.

g1t workflow disable

Turn a workflow off: its file stays, and nothing starts it until it is turned on.

g1t workflow disable [OPTIONS] [WORKFLOW]

Argument or flag
[WORKFLOW]	Its file name (ci.yml), id (wfl_…) or name; asked for at a terminal when left out.

Calls list_workflows, disable_workflow.

g1t secret

Secrets for workflows and deployments, a repository’s or a workspace’s.

g1t secret list

List secrets’ names (never their values).

g1t secret list [OPTIONS]

Argument or flag
-w, --workspace <WORKSPACE>	A workspace’s secrets instead of the repository’s.
-e, --env <ENVIRONMENT>	Only the value for this environment (production, preview…).

Calls list_actions_secrets, list_actions_secrets_for_workspace.

g1t secret set

Set a secret. The value is read from stdin when not given.

g1t secret set [OPTIONS] <NAME>

Argument or flag
<NAME>	The secret’s name; uppercased.
-b, --body <BODY>	The value. Read from stdin when left out, so it stays out of your shell’s history.
-w, --workspace <WORKSPACE>	A workspace’s secrets instead of the repository’s.
-e, --env <ENVIRONMENT>	Only the value for this environment (production, preview…).
--available-to <WHO>	Who can read it: workflows, deployments, or both (repeat).
--brokered-host <HOST>	Broker it: jobs get a stand-in, and g1t fills the value in only on requests to this host. Repeat for more.
--note <NOTE>	A note for whoever reads the list.

Calls set_actions_secret, set_actions_secret_for_workspace.

g1t secret delete

Delete a secret.

g1t secret delete [OPTIONS] <NAME>

Argument or flag
<NAME>
-w, --workspace <WORKSPACE>	A workspace’s secrets instead of the repository’s.
-e, --env <ENVIRONMENT>	Only the value for this environment (production, preview…).

Calls delete_actions_secret, delete_actions_secret_for_workspace.

g1t cache

The repository’s actions/cache entries: list, usage, delete.

g1t cache list

List the repository’s cache entries, least recently used last.

g1t cache list [OPTIONS]

Argument or flag
-k, --key <KEY>	Only entries whose key starts with this.
-g, --ref <REF>	Only entries saved by this ref’s runs, e.g. refs/heads/main.
-S, --sort <SORT>	One of last-accessed-at, created-at, size-in-bytes. Default: last-accessed-at.
-O, --order <ORDER>	One of asc, desc. Default: desc.
-L, --limit <LIMIT>	Default: 30.

Calls list_caches.

g1t cache usage

What the repository’s cache entries hold, against its quota.

g1t cache usage [OPTIONS]

Calls get_cache_usage.

g1t cache delete

Delete cache entries: one by its id, or every entry with a key.

g1t cache delete [OPTIONS] <ENTRY>

Argument or flag
<ENTRY>	An entry’s id (a number, from g1t cache list), or a key: every entry with exactly that key.
-g, --ref <REF>	With a key, only the entries this ref’s runs saved.

Calls delete_cache, delete_caches_by_key.

g1t deploy

Deployments: list and view.

g1t deploy list

List deployments, newest first.

g1t deploy list [OPTIONS]

Argument or flag
-e, --env <ENV>
-s, --state <STATE>	queued, in_progress, success, failure, error or inactive.
--source <SOURCE>	api, actions or g1t_page.
-L, --limit <LIMIT>	Default: 20.

Calls list_deployments.

g1t deploy view

Show a deployment and its statuses.

g1t deploy view [OPTIONS] <ID>

Argument or flag
<ID>
-w, --web

Calls get_deployment.

g1t logs

A project’s logs and errors.

g1t logs [OPTIONS]

Argument or flag
-p, --project <PROJECT>	The project; the current repository’s when left out.
--errors	Grouped errors instead of log lines.
-q, --query <QUERY>	Lines holding all of these words, or a “quoted phrase”.
-l, --level <LEVEL>	Levels: trace, debug, info, warn, error, fatal (comma-separated).
-e, --env <ENV>
--service <SERVICE>
-s, --since <SINCE>	How far back: 15m, 2h, 1d, or a time like 2026-10-12T09:00:00Z.
--state <STATE>	With –errors: open, resolved or ignored.
-f, --follow	Keep printing new lines as they come.
-L, --limit <LIMIT>	Default: 50.

Calls list_logs, list_errors, list_projects, get_repo.

g1t status

What needs you: your pull requests, reviews asked of you, your issues, failing checks, and your sessions and claims here.

g1t status [OPTIONS]

Calls search, list_notifications, get_pull_request, list_sessions, list_claims.

g1t session

Sessions: one run of an agent’s harness, recorded as it works.

g1t session start

Start a session and remember it for this working copy. Prints its id.

g1t session start [OPTIONS]

Argument or flag
-i, --issue <ISSUE>	The issue it works on.
-p, --pull <PULL>	The pull request it works on.
--harness <HARNESS>	The harness running it. One of claude_code, codex, cursor, copilot, other. Default: other.
--harness-session-id <ID>	The harness’s own id for the run, which makes starting again return the same session.
-t, --title <TITLE>
-b, --branch <BRANCH>	The branch it works on; the current one when left out.
--parent <SESSION>	For a subagent: the session that started it (ses_…).
--agent-type <AGENT_TYPE>	For a subagent: its kind (Explore, security-reviewer).
--task <TASK>	For a subagent: the task it was given, in a few words.
--prompt <PROMPT>	For a subagent: the prompt its parent gave it.
--model <MODEL>	The model it runs on.
--no-remember	Do not remember it as this working copy’s session (a subagent’s, kept by its harness).

The id is kept in .git/g1t/session (each worktree has its own); G1T_SESSION overrides it.
Starting again with the same --harness-session-id returns the same session.

Calls start_session.

g1t session heartbeat

Say the current session is still working; renews its claims.

g1t session heartbeat [OPTIONS]

Calls update_session.

g1t session log

Record a note, prompt or message in the current session.

g1t session log [OPTIONS] <TEXT>

Argument or flag
<TEXT>	What to record; - reads it from stdin.
-k, --kind <KIND>	One of note, prompt, message, tool_call, skill. Default: note.
--tool <TOOL>	The tool, for a tool_call.
--key <KEY>	A key that makes recording it again do nothing.

Calls record_session_entries.

g1t session attach

Attach the current session to an issue, a pull request or a branch, or give it a title.

g1t session attach [OPTIONS] <--issue <ISSUE>|--pull <PULL>|--branch <BRANCH>|--head-commit <SHA>|--title <TITLE>>

Argument or flag
-i, --issue <ISSUE>
-p, --pull <PULL>
-b, --branch <BRANCH>
--head-commit <SHA>	The commit it pushed last.
-t, --title <TITLE>	What it is for, in a few words; replaces its title.

Calls update_session.

g1t session end

End the current session.

g1t session end [OPTIONS]

Argument or flag
-r, --reason <REASON>	Why it ended: done, abandoned, handed_off…
--result <RESULT>	What it reported when it finished (a subagent’s final message); - reads it from stdin.

Calls end_session.

g1t session list

List the repository’s sessions.

g1t session list [OPTIONS]

Argument or flag
-s, --state <STATE>	Only sessions in this state. One of active, idle, ended.
-i, --issue <ISSUE>
-p, --pull <PULL>
-L, --limit <LIMIT>	Default: 20.
--path <PATH>	Only sessions that touched this file, or any under it when it ends in /.
--subagents	List subagents too, under the sessions that started them.

Calls list_sessions.

g1t session view

Show a session and what it recorded; the current one when left out.

g1t session view [OPTIONS] [ID]

Argument or flag
[ID]	The session’s id (ses_…); the current one when left out.

Calls get_session.

g1t session touch

Say what the current session touched: files, commits, branches, pull requests, issues.

g1t session touch [OPTIONS] <--file <FILE>|--commit <COMMIT>|--branch <BRANCH>|--pull <PULL>|--issue <ISSUE>>

Argument or flag
--file <FILE>	A file it wrote, from the repository’s root. Repeat for more.
--commit <COMMIT>	A commit it made.
--branch <BRANCH>	A branch it pushed.
--pull <PULL>	A pull request it opened.
--issue <ISSUE>	An issue it named.

Each is kept once. A file another active session touched too (a sibling subagent's included)
is an overlap.detected event for both. Pull requests and issues tie the session to them.

Calls record_session_entries.

g1t work

Coordinate work on issues: context, claims, hand-offs, dependencies, events.

g1t work context

Everything about an issue’s work: claims, sessions, pull requests, dependencies, decisions.

g1t work context [OPTIONS] <NUMBER>

Argument or flag
<NUMBER>	The issue’s number.

Calls get_work.

g1t work claim

Claim an issue: say you are working on it. Others are told, never stopped.

g1t work claim [OPTIONS] <NUMBER|--title <TITLE>>

Argument or flag
[NUMBER]	The issue’s number.
--title <TITLE>	Open a new issue with this title and claim it; the current session is attached to it.
--body <BODY>	The new issue’s description.
-n, --note <NOTE>	What you are doing about it.
--ttl <DURATION>	How long the claim lasts unless renewed: 30m, 2h (at most 4h).

With --title instead of a number, a new issue is opened and claimed in one step, and the
current session is attached to it: for work that became a change others should know about.
Examples:
  g1t work claim 12 --note "Rewriting the retry loop"
  g1t work claim --title "Preview builds time out on large repositories"

Calls claim_issue, claim_new_issue.

g1t work release

Release your claim on an issue.

g1t work release [OPTIONS] <NUMBER>

Argument or flag
<NUMBER>
-r, --reason <REASON>	Why: done, blocked, abandoned…

Calls release_claim.

g1t work handoff

Hand an issue over to someone else, or to anyone.

g1t work handoff [OPTIONS] --note <NOTE> <NUMBER>

Argument or flag
<NUMBER>
--to <LOGIN>	Who takes it over; anyone when left out.
-n, --note <NOTE>	Where it stands and what is left, for whoever takes it.

Calls hand_off_issue.

g1t work list

Active claims and sessions in the repository.

g1t work list [OPTIONS]

Calls list_claims, list_sessions.

g1t work block

Say an issue waits on others: it is blocked by them.

g1t work block [OPTIONS] --by <NUMBER> <NUMBER>

Argument or flag
<NUMBER>	The issue that waits.
--by <NUMBER>	The issue it waits on; repeat for more.

Calls get_issue, update_issue.

g1t work unblock

Say an issue no longer waits on others.

g1t work unblock [OPTIONS] --by <NUMBER> <NUMBER>

Argument or flag
<NUMBER>	The issue that waits.
--by <NUMBER>	The issue it waits on; repeat for more.

Calls get_issue, update_issue.

g1t work events

The repository’s events; –follow keeps printing them as they happen.

g1t work events [OPTIONS]

Argument or flag
-f, --follow	Keep printing events as they happen, until stopped.
-t, --type <TYPE>	Only events of this type; repeat for more.
-i, --issue <NUMBER>	Only events about this issue or pull request; repeat for more.
-s, --since <SINCE>	Only events since then: 15m, 2h, 1d, or a time like 2026-10-12T09:00:00Z.
--after <EVENT_ID>	Start after this event id, as a follow that stopped would resume.
-L, --limit <LIMIT>	How many past events to show first. Default: 20.

Examples:
  g1t work events --follow --issue 12
  g1t work events --follow --type integration.failed --type overlap.detected --json
With --json, each event is one JSON object on a line of its own.

Calls list_events.

g1t work dispatch

Start work on an issue in a session on your own Claude, or print the Claude Code command for it.

g1t work dispatch [OPTIONS] <NUMBER|--title <TITLE>>

Argument or flag
[NUMBER]	The issue’s number.
--title <TITLE>	Open a new issue with this title and work on it.
--body <BODY>	The new issue’s description.
-i, --instruction <INSTRUCTION>	What to do beyond what the issue says.
-m, --mode <MODE>	What kind of work. One of plan, implement, review.
--handoff	Print the Claude Code command to run yourself; start nothing.
--managed	Start it on the workspace’s Anthropic account, or fail.

With the workspace's Anthropic connection, a Claude Managed Agents session starts on that
account and is recorded on g1t; otherwise (or with --handoff) this prints a `claude` command
to run with g1t's plugin, whose session attaches to the issue as it starts.
Examples:
  g1t work dispatch 12
  g1t work dispatch 12 --mode plan --instruction "Keep the old flag"
  g1t work dispatch --title "Add a healthcheck" --handoff

Calls start_agent_session.

g1t why

Why a file or line is as it is: its commit, pull request, issue, decisions and sessions.

g1t why [OPTIONS] <TARGET>

Argument or flag
<TARGET>	A file, or a line of it as PATH:LINE.
--ref <REF>	The branch, tag or commit to read it at; the default branch when left out.

Calls why.

g1t api

Call any API operation or path, with your token.

g1t api [OPTIONS] [ENDPOINT]

Argument or flag
[ENDPOINT]	An operation’s name, or a path.
--list [QUERY]	List the operations, or those matching this word.
-X, --method <METHOD>	The HTTP method: GET unless fields are given, then POST.
-f, --raw-field <KEY=VALUE>	A string field, key=value. key[]=value adds to a list.
-F, --field <KEY=VALUE>	A typed field: true, false, null and numbers become JSON; @file reads a file.
-H, --header <KEY:VALUE>	A request header, key:value.
--input <FILE>	The request body, from a file or - for stdin.
--paginate	Follow next pages until there are none.
--slurp	With –paginate, put every page’s items into one array.
-i, --include	Print the status line and headers too.
--silent	Print nothing on success.

ENDPOINT is an operation's name (list_issues) or a path (/repos/{owner}/{name}/issues).
{owner}, {name}, {repo} and {workspace} are filled in from the current repository,
and an operation's other path parameters from -f/-F fields of the same name.

Examples:
  g1t api list_issues -f state=closed
  g1t api /user --jq .username
  g1t api create_issue -f title='Broken link' -f labels[]=docs
  g1t api list_workflow_runs --paginate --jq '.[].conclusion'
  g1t api --list issue

g1t browse

Open the repository, an issue or a pull request in the browser.

g1t browse [OPTIONS] [TARGET]

Argument or flag
[TARGET]	An issue or pull request number, a file path (path:line), or a commit.
-b, --branch <BRANCH>	The branch to show files on.
-s, --settings
--issues
--pulls
--actions
-n, --no-browser	Print the address instead of opening it.

g1t alias

Shortcuts for commands you type often.

g1t alias set

Make an alias: g1t alias set co ‘pr checkout’. Start it with ! to run it through the shell.

g1t alias set [OPTIONS] <NAME> <EXPANSION>

Argument or flag
<NAME>
<EXPANSION>	What it expands to. $1, $2… take the arguments after it.

g1t alias list

List aliases.

g1t alias list [OPTIONS]

g1t alias delete

Delete an alias.

g1t alias delete [OPTIONS] <NAME>

Argument or flag
<NAME>

g1t completion

Print a shell completion script.

g1t completion [OPTIONS] <SHELL>

Argument or flag
<SHELL>	One of bash, elvish, fish, powershell, zsh.

g1t push

Push a local container image to g1t’s registry, in chunks.

g1t push [OPTIONS] [IMAGE]

Argument or flag
[IMAGE]	The local image, [REGISTRY/]NAME[:TAG].
--as <ADDRESS>	Where to push, when the image’s own name is not an address on g1t.sh. The tag defaults to latest.
--chunk-size <SIZE>	How much of a layer each request carries: 5MB to 95MB. Default: 90MB.
--token-stdin	Read the g1t token from stdin.
--archive <FILE>	Push a tarball docker save wrote, instead of asking docker for the image.

The token is the first of: --token-stdin, G1T_TOKEN, the account `g1t auth login`
signed in for the registry's host, or what `docker login g1t.sh` stored.