gm commands

Every gm command, its arguments and examples: 173 commands, generated from gm itself.

This reference comes from gm cli commands, the same manifest agents read. For one command's arguments and its JSON output shape, run gm schema <command>; to find a command by what you want to do, run gm cli search "<task>".

gm tracker

gm tracker list

List trackers visible to the authenticated account (online only)

gm tracker list [OPTIONS]

--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm tracker list

gm tracker usechanges state

Select a tracker and initialize its authenticated offline replica

gm tracker use [OPTIONS] <OWNER>

owner: Required.
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm tracker use orbit

gm tracker syncchanges state

Replay ordered durable operations, then pull the cursor feed

gm tracker sync [OPTIONS]

--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm tracker sync

gm tracker status

Show replica cursor, pending operations and identity

gm tracker status [OPTIONS]

--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm tracker status --offline

gm tracker conflicts

Show blocked operations with preserved local edits and current server data

gm tracker conflicts [OPTIONS]

--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm tracker conflicts

gm tracker resolvechanges state

Resolve the head conflict explicitly; later operations remain queued

gm tracker resolve [OPTIONS] --strategy <STRATEGY> <OPERATION>

operation: Required.
--strategy <accept-server|reapply-local>: Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm tracker resolve OPERATION --strategy reapply-local

gm tracker changes

Read bounded authoritative changes after an explicit cursor (online only)

gm tracker changes [OPTIONS]

--after <after>: Default: 0.
--limit <limit>: Default: 100.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm tracker changes --after 10 --limit 50

gm tracker recoverchanges state

Recover an old credential partition's outbox after verifying the same server identity

gm tracker recover [OPTIONS] <REPLICA>

replica: Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm tracker recover /private/old/orbit.sqlite --owner orbit

gm team

gm team list

List teams and membership

gm team list [OPTIONS]

--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm team list

gm team createchanges state

Create a team with an immutable issue-key prefix

gm team create [OPTIONS] --name <NAME> <KEY>

key: Immutable team key or workspace slug Required.
--name <name>: Required.
--description <description>: Default: .
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm team create ENG --name Engineering

gm team updatechanges state

Update name, description, memberIds or archived with version checking

gm team update [OPTIONS] --data <DATA> <ID>

id: Canonical ID, team key or workspace slug Required.
--data <data>: JSON object of mutable fields; use '-' for stdin or '@path' for a file. Team fields: name, description, memberIds and archived. Workspace fields: name, description and archived. Member IDs are canonical Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm team update ENG --data '{"name":"Platform"}'

gm workspace

gm workspace list

List cross-team workspaces

gm workspace list [OPTIONS]

--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm workspace list

gm workspace createchanges state

Create a workspace with an immutable slug

gm workspace create [OPTIONS] --name <NAME> <KEY>

key: Immutable team key or workspace slug Required.
--name <name>: Required.
--description <description>: Default: .
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm workspace create launch --name Launch

gm workspace updatechanges state

Update name, description or archived with version checking

gm workspace update [OPTIONS] --data <DATA> <ID>

id: Canonical ID, team key or workspace slug Required.
--data <data>: JSON object of mutable fields; use '-' for stdin or '@path' for a file. Team fields: name, description, memberIds and archived. Workspace fields: name, description and archived. Member IDs are canonical Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm workspace update launch --data '{"archived":true}'

gm workspace subscribechanges state

Associate an authorized repository ID with a workspace; grants no membership

gm workspace subscribe [OPTIONS] --repo <REPO> <WORKSPACE>

workspace: Required.
--repo <repo>: Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm workspace subscribe launch --repo REPO_ID

gm workspace unsubscribechanges state

Remove a subscription by its canonical ID

gm workspace unsubscribe [OPTIONS] <ID>

id: Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm workspace unsubscribe SUBSCRIPTION_ID

gm issue

gm issue createchanges state

Create a ticket or full Markdown PRD with a stable offline ID

gm issue create [OPTIONS] <TITLE>

title: Required.
--team <team>: Defaults to this checkout's or the project's team, then your default team (set on the web)
--description <description>
--description-file <description-file>: Markdown file, or '-' for stdin
--acceptance <acceptance>
--acceptance-file <acceptance-file>: Acceptance criteria file, or '-' for stdin
--type <task|bug|prd|chore|research|remediation>: Default: task.
--status <backlog|todo|in_progress|done|canceled>: Default: todo.
--close-reason <duplicate|not_planned|obsolete|cannot_reproduce|other>: Required for canceled issues; forbidden for other statuses
--pickup <anyone|not_ready|human_only>: Who may pick up the issue: anyone (default), nobody yet, or people only Default: anyone.
--priority <priority>: Default: 2.
--timeline-use <agent_decides|required|never>: Whether agents work this issue in a timeline: agent_decides (the default; the agent also reads the description or PRD), required or never
--timeline-policy <auto|approval|none>: With required: the policy the agent's timeline must use (auto or approval); none leaves it to the agent
--parent <parent>
--assignee <assignee>
--workspace <workspace>…
--tag <tag>…: Work-area tag from the tracker's tag catalog; repeat for each area (e.g. --tag ux --tag frontend). `gm issue tags` lists the catalog; a new name is added to it. Tags describe the issue and do not restrict claims; --requires says which agents may claim it. (`--label` is the old name of this flag.)
--requires <requires>: Which agents may claim it, from what they report (`gm agent setup`): space-separated terms like 'tag:ux skill:playwright model:claude-opus-*,gpt-5* harness:claude-code os:linux arch:x86_64 runtime:host memory>=16GiB cpus>=8'. Tags and skills: every one; the rest: any one; `*` is a wildcard. Agents that don't meet them can't claim it and `gm issue next` skips it. People bypass capability requirements, but not pickup policy
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue create 'Ship search' --team ENG --type prd --description-file spec.md --pickup not_ready
gm issue create 'Migrate billing' --team ENG --timeline-use required --timeline-policy approval
gm issue create 'Polish onboarding' --team ENG --requires 'tag:ux skill:playwright'
gm issue create 'Fix keyboard navigation' --team ENG --tag ux --tag frontend

gm issue list

List issues with bounded filtering

gm issue list [OPTIONS]

--team <team>: Defaults to this checkout's or the project's team, then your default team (set on the web)
--all-teams: Ignore every default team and list across all teams
--workspace <workspace>
--status <status>
--type <task|bug|prd|chore|research|remediation>: Filter by issue type, including automatic queue remediation
--search <search>
--limit <limit>: Default: 50.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue list --workspace launch --limit 20
gm issue list --type remediation

gm issue ready

Find unblocked, unclaimed work; offline readiness is advisory only

gm issue ready [OPTIONS]

--team <team>: Defaults to this checkout's or the project's team, then your default team (set on the web)
--all-teams: Ignore every default team and list across all teams
--workspace <workspace>
--status <status>
--type <task|bug|prd|chore|research|remediation>: Filter by issue type, including automatic queue remediation
--search <search>
--limit <limit>: Default: 50.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue ready --limit 10
gm issue ready --type remediation

gm issue tags

The tracker's tag catalog: every tag defined (kept after its last use), with how many issues carry it

gm issue tags [OPTIONS]

--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue tags
gm issue tags --owner orbit -o json

gm issue show

Inspect an issue and bounded ancestors, blockers, dependents and notes, with its requirements and whether the acting agent meets them

gm issue show [OPTIONS] <ISSUE>

issue: Required.
--limit <limit>: Default: 30.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue show ENG-1 --limit 20

gm issue history

Read the complete audit trail, newest first (online only)

gm issue history [OPTIONS] <ISSUE>

issue: Canonical issue ID or key Required.
--before <before>: Exclusive cursor from the previous page's nextBefore
--limit <limit>: Default: 50.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue history ENG-1 --owner orbit --limit 50
gm issue history ENG-1 --owner orbit --before 120 --json

gm issue updatechanges state

Apply a JSON patch with optimistic version checking; null clears nullable fields. --timeline-use and --timeline-policy set the timeline rule without JSON; --requires and --clear-requires set which agents may claim it

gm issue update [OPTIONS] <ID>

id: Canonical ID or issue key Required.
--data <data>: JSON object of mutable fields; use '-' for stdin or '@path' for a file: title, description, acceptance, type, status, closeReason, timelineUse, timelinePolicy, priority (0–4), assigneeId, parentId, workspaceIds, tags (the whole list; `labels` is its old name), pickup and requires (an object, or null; --requires writes it from terms). Relationships use canonical IDs; null clears assigneeId/parentId. Setting status to canceled requires closeReason: duplicate, not_planned, obsolete, cannot_reproduce or other. Leaving canceled clears closeReason automatically, as leaving required clears timelinePolicy
--pickup <anyone|not_ready|human_only>: Pickup policy; only a person can change an existing restricted policy
--tag <tag>…: Add a tag from the tracker's tag catalog (repeat); keeps its other tags. (`--label` is the old name of this flag.)
--drop-tag <drop-tag>…: Remove a tag (repeat)
--require-issue-tags: Require agents tagged with this issue's saved tags: adds a `tag:` term for each to its requirements
--release-claim: When new requirements no longer allow the agent holding the issue, release its claim instead of keeping it (tracker owners and the agent's person). Either way gm prints who's affected and the issue records it
--timeline-use <agent_decides|required|never>: Whether agents work this issue in a timeline: agent_decides (the default; the agent also reads the description or PRD), required or never
--timeline-policy <auto|approval|none>: With required: the policy the agent's timeline must use (auto or approval); none leaves it to the agent
--requires <requires>: Which agents may claim it, from what they report (`gm agent setup`): space-separated terms like 'tag:ux skill:playwright model:claude-opus-*,gpt-5* harness:claude-code os:linux arch:x86_64 runtime:host memory>=16GiB cpus>=8'. Tags and skills: every one; the rest: any one; `*` is a wildcard. Agents that don't meet them can't claim it and `gm issue next` skips it. People bypass capability requirements, but not pickup policy
--clear-requires: Remove capability requirements (requires: null); does not change pickup policy
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue update ENG-1 --data '{"priority":1}' --offline
gm issue update ENG-1 --tag ux --drop-tag backend
gm issue update ENG-1 --require-issue-tags
gm issue update ENG-1 --requires 'tag:gpu' --release-claim
gm issue update ENG-1 --timeline-use required --timeline-policy auto
gm issue update ENG-1 --pickup human_only
gm issue update ENG-1 --clear-requires

gm issue linkchanges state

Add a directed relation: FROM blocks TO (or related/duplicates)

gm issue link [OPTIONS] <FROM> <TO>

from: Required.
to: Required.
--kind <blocks|related|duplicates>: Default: blocks.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue link ENG-1 ENG-2 --kind blocks

gm issue unlinkchanges state

Remove a relationship by canonical ID

gm issue unlink [OPTIONS] <ID>

id: Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue unlink LINK_ID

gm issue commentchanges state

Append a durable Markdown comment

gm issue comment [OPTIONS] <ISSUE> <BODY>

issue: Required.
body: Markdown text; '-' reads stdin and '@path' reads a file Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue comment ENG-1 'Investigating the failing build'

gm issue checkpointchanges state

Append a durable agent checkpoint (progress, decisions and next actions)

gm issue checkpoint [OPTIONS] <ISSUE> <BODY>

issue: Required.
body: Markdown text; '-' reads stdin and '@path' reads a file Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue checkpoint ENG-1 '@checkpoint.md'

gm issue evidencechanges state

Append durable completion or verification evidence

gm issue evidence [OPTIONS] <ISSUE> <BODY>

issue: Required.
body: Markdown text; '-' reads stdin and '@path' reads a file Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue evidence ENG-1 'Verified with integration smoke'

gm issue claimchanges state

Atomically acquire exclusive work online; returns the secret fencing token once

gm issue claim [OPTIONS] <ISSUE>

issue: Required.
--agent <agent>: A session name for this piece of work; defaults to this checkout's agent (`gm agent setup`)
--ttl <ttl>: Lease seconds; defaults to .gitmatrix/agents.yml's, else 900
--under-token <under-token>: The lease token of the issue whose subtree this is; prefer GM_UNDER_TOKEN
--for <for>: Hold the claim as one of your agents (name or id) instead of yourself
--force: Take over someone else's active claim (tracker owners, as themselves). Their token stops working; the takeover is noted on the issue
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue claim ENG-1
gm issue claim ENG-1 --agent build-agent
GM_UNDER_TOKEN=… gm issue claim ENG-12 --agent sub --for reviewer
gm issue claim ENG-1 --force

gm issue askchanges state

Ask a person for something: a question, an approval, a decision or a credential. With the issue's lease token the lease is parked while you wait

gm issue ask [OPTIONS] --kind <KIND> --prompt <PROMPT> <ISSUE>

issue: Required.
--kind <question|approval|decision|credential>: Required.
--prompt <prompt>: Markdown; '-' reads stdin and '@path' reads a file Required.
--choice <choice>…: For a decision: an option (repeat for each)
--secret <secret>: For a credential: the secret to store the answer as, owner/repo:NAME
--route-to <route-to>: Ask this member (slug) instead of your accountable person
--lease-token <lease-token>: The issue's lease token, to park the lease; prefer GM_LEASE_TOKEN
--checkpoint <checkpoint>: For an approval: the timeline checkpoint to approve (its id, from `gm timeline checkpoint`). It must be the timeline's head; new commits need a new checkpoint
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

GM_LEASE_TOKEN=… gm issue ask ENG-3 --kind question --prompt "Which region should this deploy to?"
gm issue ask ENG-3 --kind decision --prompt "Which store?" --choice D1 --choice R2
gm issue ask ENG-3 --kind approval --checkpoint cp_… --prompt "Land search-v2?"

gm issue resumechanges state

Take a parked lease back up once its requests are answered; returns a fresh token

gm issue resume [OPTIONS] <ISSUE>

issue: Required.
--ttl <ttl>: Lease seconds; defaults to .gitmatrix/agents.yml's, else 900
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue resume ENG-3

gm issue handoffchanges state

Hand your lease to another agent or person: prints a single-use code. You keep the lease until it's accepted

gm issue handoff [OPTIONS] <ISSUE>

issue: Required.
--lease-token <lease-token>: Fencing token; defaults to the one gm kept when this identity claimed the issue. Otherwise prefer GM_LEASE_TOKEN to avoid shell history/process arguments
--to <to>: Only this agent (name or id) or member (slug) may accept
--ttl <ttl>: How long the code works, in seconds Default: 600.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

GM_LEASE_TOKEN=… gm issue handoff ENG-3 --to reviewer

gm issue withdrawchanges state

Withdraw a pending handoff of your lease

gm issue withdraw [OPTIONS] <ISSUE>

issue: Required.
--lease-token <lease-token>: Fencing token; defaults to the one gm kept when this identity claimed the issue. Otherwise prefer GM_LEASE_TOKEN to avoid shell history/process arguments
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

GM_LEASE_TOKEN=… gm issue withdraw ENG-3

gm issue acceptchanges state

Accept a handoff code: the lease moves to you with a fresh token; the giver's stops working

gm issue accept [OPTIONS] <CODE>

code: Required.
--agent <agent>: A session name for this piece of work (defaults to the giver's)
--ttl <ttl>: Lease seconds; defaults to .gitmatrix/agents.yml's, else 900
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue accept ENG-3.4f…

gm issue revokechanges state

Take back a claim inside your leased subtree; its token stops working

gm issue revoke [OPTIONS] --under-token <UNDER_TOKEN> <ISSUE>

issue: Required.
--under-token <under-token>: The lease token of an issue above it; prefer GM_UNDER_TOKEN Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

GM_UNDER_TOKEN=… gm issue revoke ENG-12

gm issue nextchanges state

Pick and claim the next ready issue in one step: highest priority, then most unblocked work, then oldest. Returns its token once, with the issue's working context. An agent only gets issues whose requirements it meets; the result says how many it skipped

gm issue next [OPTIONS]

--agent <agent>: A session name for this piece of work; defaults to this checkout's agent (`gm agent setup`)
--team <team>: Defaults to this checkout's scope, then the project's (.gitmatrix/agents.yml), then your default team (set on the web)
--all-teams: Ignore every default team and pick from all teams
--workspace <workspace>
--under <under>: Only work under this issue (a project or other parent)
--ttl <ttl>: Lease seconds; defaults to .gitmatrix/agents.yml's, else 900
--under-token <under-token>: The lease token of the issue whose subtree this is; prefer GM_UNDER_TOKEN
--for <for>: Hold the claim as one of your agents (name or id) instead of yourself
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue next
gm issue next --under CORE-4
gm issue next --agent builder --team CORE
gm issue next --timeline search

gm issue renewchanges state

Renew an online fenced lease; returns its token only in this response

gm issue renew [OPTIONS] <ISSUE>

issue: Required.
--lease-token <lease-token>: Fencing token; defaults to the one gm kept when this identity claimed the issue. Otherwise prefer GM_LEASE_TOKEN to avoid shell history/process arguments
--ttl <ttl>: Lease seconds; defaults to .gitmatrix/agents.yml's, else 900
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue renew ENG-1 --ttl 900

gm issue releasechanges state

Release the current fenced lease online

gm issue release [OPTIONS] <ISSUE>

issue: Required.
--lease-token <lease-token>: Fencing token; defaults to the one gm kept when this identity claimed the issue. Otherwise prefer GM_LEASE_TOKEN to avoid shell history/process arguments
--force: End someone else's claim without its token (tracker owners, as themselves); noted on the issue, not counted as their failure
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue release ENG-1
gm issue release ENG-1 --force

gm issue completechanges state

Complete claimed work online with durable evidence and a valid fencing token

gm issue complete [OPTIONS] --evidence <EVIDENCE> <ISSUE>

issue: Required.
--lease-token <lease-token>: Fencing token; defaults to the one gm kept when this identity claimed the issue. Otherwise prefer GM_LEASE_TOKEN to avoid shell history/process arguments
--evidence <evidence>: Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue complete ENG-1 --evidence '@verification.md'

gm issue batchchanges state

Queue one atomic mutation array (max 100). Create referenced IDs before using them; '-' reads stdin, '@path' reads a file

gm issue batch [OPTIONS] <DATA>

data: JSON array of {kind,id,expectedVersion?,data?}; use canonical IDs. Kinds: team.create/update, workspace.create/update, issue.create/update, link.add/remove, comment.add, subscription.add/remove. Lease operations are online-only and cannot be queued. Create data: team {key,name,description?,memberIds?}; workspace {slug,name,description?}; issue {teamId,title,...issue update fields}. Updates use the fields documented by `gm schema issue update`. link.add data: {fromId,toId,kind:blocks|related|duplicates}. comment.add data: {issueId,body,kind:comment|checkpoint|evidence}. subscription.add data: {workspaceId,repoId}. Removes need only kind/id. Updates require expectedVersion. Referenced creates must appear earlier Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm issue batch '@plan.json' --offline

gm request

gm request list

Requests to people in this tracker: yours first. Include answers to resume parked work

gm request list [OPTIONS]

--status <open|answered|canceled|all>: Default: open.
--issue <issue>: Limit requests to an issue's canonical ID or key
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm request list
gm request list --status answered
gm request list --issue ENG-3 --status all

gm request answerchanges state

Answer a request: --answer for a question, --choice for a decision, --approve/--reject; a credential asks for its value (hidden) and stores it as its secret

gm request answer [OPTIONS] <ID>

id: Required.
--answer <answer>
--choice <choice>
--approve
--reject
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm request answer 3f2c --answer eu-west
gm request answer 3f2c --approve
gm request answer 3f2c   # a credential: prompts for the value

gm request cancelchanges state

Withdraw a request you asked

gm request cancel [OPTIONS] <ID>

id: Required.
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--offline: Use only this private SQLite replica. Never automatically falls back offline
--timeline <timeline>: Work in a timeline (its slug): read its view of the issues, and make changes in it. Defaults to GM_TIMELINE, then this checkout's timeline (`gm timeline use`); `main` is main's view

gm request cancel 3f2c

gm status

Show the working-copy change, its files and where it sits relative to trunk

Like git status

gm status

gm status

gm log

List changes: your unpushed work and the trunk commit it builds on

Like git log --oneline --graph

gm log [OPTIONS]

r, --revisions <revisions>: Revision or range: `@`, a change id, `A..B`, or `all`. Default: your mutable changes plus trunk
n, --limit <limit>: Maximum number of changes Default: 50.
--context: Add each step's why (from `gm commit --context`), from the server or this checkout

gm log
gm log -r all -n 20
gm log -r trunk..@
gm log --context

gm show

Show one change: its description and diff

Like git show

gm show [OPTIONS] [REVISION]

revision: Revision to show Default: @.
--stat: Only list files and line counts
--context: Add the step's context: why, instructions, steering, challenges, tests

gm show
gm show @- --stat
gm show @- --context

gm diff

Show the diff of a change (default: the working copy) or between two revisions

Like git diff

gm diff [OPTIONS] [PATHS]...

paths: Limit to these paths
r, --revision <revision>: Change to diff against its parent
--from <from>: Diff from this revision (with --to)
--to <to>: Diff to this revision (default `@`)
--stat: Only list files and line counts

gm diff
gm diff --stat
gm diff --from trunk --to @
gm diff src/

gm describe

gm describechanges state

Set the description (commit message) of a change, by default the working copy

Like git commit --amend -m (message only)

gm describe --message <MESSAGE> [REVISION]

revision: Change to describe Default: @.
m, --message <message>…: The description. Several -m flags become paragraphs Required.

gm describe -m "Fix login redirect"
gm describe @- -m "Better message"

gm new

gm newchanges state

Start a new empty change on top of one or more revisions (several = a merge)

Like git switch -c / git stash / git merge --no-commit

gm new [OPTIONS] [REVISIONS]...

revisions: Parent revisions (default `@`). Two or more make a merge
m, --message <message>…: Description for the new change

gm new
gm new trunk -m "Try another approach"
gm new kxyz lmno

gm merge

gm mergechanges state

Merge revisions (main, a bookmark, a change) into a new merge change below the working copy

Like git merge --no-ff

gm merge [OPTIONS] <REVISIONS>...

revisions: Revisions to merge into `@-`, e.g. `trunk` or a bookmark. Several make an octopus merge Required.
m, --message <message>…: Description for the merge (default "Merge <revisions>")

gm merge trunk
gm merge feature-x -m "Merge feature-x"
gm merge kxyz lmno

gm commit

gm commitchanges state

Describe the working-copy change and start a new one on top: the "save my work" step

Like git commit -am

gm commit [OPTIONS] --message <MESSAGE> [PATHS]...

paths: Commit only these paths; the rest stays in the new working copy
m, --message <message>…: Description for the change being committed (the current working copy) Required.
--context <context>: Step context for this commit (CORE-226): a JSON or Markdown file, or `-` for stdin, with instructions, steering, why, challenges (and tests). Journaled locally and uploaded by `gm push`

gm commit -m "Add retry to fetch"
gm commit -m "Only the docs" docs/

gm squash

gm squashchanges state

Move a change's edits into another change (default: the working copy into its parent)

Like git commit --amend / git rebase -i fixup

gm squash [OPTIONS] [PATHS]...

paths: Move only these paths
r, --revision <revision>: Change to take edits from Default: @.
--into <into>: Change to put them into (default: the parent of --revision)
m, --message <message>…: New description for the destination

gm squash
gm squash -r kxyz --into lmno
gm squash src/a.rs

gm split

gm splitchanges state

Split selected files out of a change into a new change before it

Like git add -p && git commit (partial)

gm split [OPTIONS] --message <MESSAGE> <PATHS>...

paths: Paths to split out Required.
r, --revision <revision>: Change to split Default: @.
m, --message <message>…: Description for the new change holding the selected paths Required.

gm split -m "Extract parser" src/parser.rs

gm edit

gm editchanges state

Make an existing change the working copy, to keep editing it in place

Like git checkout <commit> (to amend in place)

gm edit <REVISION>

revision: Change to edit Required.

gm edit kxyz

gm abandon

gm abandonchanges state

Drop changes; their descendants are rebased onto their parents

Like git reset --hard HEAD~ / git rebase --onto (drop)

gm abandon [REVISIONS]...

revisions: Changes to drop (default `@`)

gm abandon
gm abandon kxyz

gm restore

gm restorechanges state

Discard edits: restore files from another revision (default: the parent)

Like git restore / git checkout -- <path> / git reset --hard

gm restore [OPTIONS] [PATHS]...

paths: Paths to restore (default: everything)
--from <from>: Take file contents from this revision (default: the parent of --into)
--into <into>: Change to restore files in Default: @.

gm restore
gm restore src/main.rs
gm restore --from trunk Cargo.lock

gm rebase

gm rebasechanges state

Move changes (and their descendants) onto another revision

Like git rebase

gm rebase [OPTIONS]

s, --source <source>: Rebase this change and its descendants
r, --revision <revision>: Rebase only this change; its descendants stay where they are
b, --branch <branch>: Rebase the whole stack containing this change (default `@`)
d, --destination <destination>: Destination (default `trunk`) Default: trunk.

gm rebase
gm rebase -s kxyz -d trunk
gm rebase -r kxyz -d lmno

gm backout

gm backoutchanges state

Add a change that reverses another change, just below the working copy

Like git revert

gm backout --revision <REVISION>

r, --revision <revision>: Change to reverse Required.

gm backout -r kxyz

gm duplicate

gm duplicatechanges state

Copy a change (cherry-pick); by default insert the copy below the working copy

Like git cherry-pick

gm duplicate [OPTIONS] <REVISION>

revision: Change to copy Required.
d, --destination <destination>: Put the copy on top of this revision instead of below the working copy

gm duplicate kxyz
gm duplicate kxyz -d trunk

gm undo

gm undochanges state

Undo the last operation; repeat to go further back

Like git reflog + git reset (roughly)

gm undo

gm undo

gm op

gm op log

List recent operations, newest first

Like git reflog

gm op log [OPTIONS]

n, --limit <limit>: Default: 20.

gm op log -n 5

gm op restorechanges state

Put the repository back to how it was right after an operation

Like git reset --hard <reflog entry>

gm op restore <OPERATION>

operation: Operation id from `gm op log` Required.

gm op restore 3fa2c1d09b7e

gm bookmark

gm bookmark list

List local bookmarks and their remote counterparts

Like git branch -a

gm bookmark list

gm bookmark list

gm bookmark setchanges state

Create or move a bookmark

Like git branch -f

gm bookmark set [OPTIONS] <NAME>

name: Required.
r, --revision <revision>: Revision to point at Default: @.

gm bookmark set feature-x
gm bookmark set feature-x -r @-

gm bookmark deletechanges state

Delete a bookmark

Like git branch -D / git push --delete

gm bookmark delete [OPTIONS] <NAME>

name: Required.
--remote: Also delete it on the server

gm bookmark delete feature-x
gm bookmark delete feature-x --remote

gm file

gm file show

Print a file's contents at a revision

Like git show <rev>:<path>

gm file show [OPTIONS] <PATH>

path: Required.
r, --revision <revision>: Default: @.

gm file show src/main.rs -r trunk

gm file list

List files at a revision

Like git ls-tree -r --name-only

gm file list [OPTIONS] [PATH]

path: Only under this directory
r, --revision <revision>: Default: @.

gm file list
gm file list src -r trunk

gm why

Why did these lines change? Blame, then the change's timelines, issues, checkpoints, approval and landing

Like git blame -L

gm why [OPTIONS] <TARGET>

target: A file and line: `src/app.ts:12` or `src/app.ts:12-20`; or just the file, with --line Required.
L, --line <line>: The line or range (12, 12-20), when the target names only the file
r, --rev <rev>: Revision to blame at (default: the working copy) Default: @.
R, --repo <repo>: Repository on the server as owner/name (default: this repository's origin)

gm why src/app.ts:42
gm why src/app.ts -L 40-48 --rev trunk
gm why apps/cli/src/main.rs:10 -o text

gm worktree

gm worktree addchanges state

Create an initialized, detached worktree with its own working-copy change

Like git worktree add --detach

gm worktree add [OPTIONS] <PATH>

path: Destination directory, relative to --cwd Required.
r, --revision <revision>: Revision to build on; defaults to the current working-copy snapshot Default: @.
--include: Copy ignored files matching the source checkout's .worktreeinclude. The checkout's agent (.gitmatrix/agent.local.yml) is always copied

gm worktree add ../feature
gm worktree add ../feature -r trunk --include

gm worktree list

List the main checkout and linked worktrees, including non-gm worktrees

Like git worktree list

gm worktree list

gm worktree list

gm worktree removechanges state

Remove a linked worktree; its gm history is retained for recovery

Like git worktree remove

gm worktree remove [OPTIONS] <PATH>

path: Worktree directory, relative to --cwd Required.
--force: Discard modified, untracked and ignored files; locked worktrees still refuse removal

gm worktree remove ../feature
gm worktree remove ../feature --force

gm init

gm initchanges state

Start using gm in the current git repository

Like git init (then adopt)

gm init

gm init

gm clone

gm clonechanges state

Clone a Gitmatrix repository and set it up for gm

Like git clone

gm clone [OPTIONS] <REPOSITORY> [DIRECTORY]

repository: Repository as owner/name Required.
directory: Directory to clone into (default: the repository name)
q, --quiet: Suppress live progress on stderr (the final result and errors remain)

gm clone orbit/engine
gm clone orbit/engine ./engine
gm clone orbit/engine --quiet

gm fetch

gm fetchchanges state

Download new commits from Gitmatrix without changing your changes

Like git fetch

gm fetch

gm fetch

gm sync

gm syncchanges state

Fetch, then rebase your changes onto the new trunk

Like git pull --rebase

gm sync

gm sync

gm push

gm pushchanges state

Land changes on trunk (or a bookmark) on Gitmatrix. There are no pull requests

Like git push

gm push [OPTIONS]

r, --revision <revision>: Change to push (default `@`, or `@-` when `@` is empty). Its ancestors go too
b, --bookmark <bookmark>: Push to this bookmark instead of trunk, creating or moving it. In a checkout working in a timeline, trunk is `timeline/<slug>` and main is refused
--sync: Fetch and rebase onto the latest trunk first
--queue: Upload for server-side merge gates without advancing main immediately
--issue <issue>…: Link an issue key or ID to this queue admission (repeatable)

gm push --queue --issue ENG-1
gm push
gm push --sync
gm push -b feature-x

gm queue

gm queue list

Recent admissions, newest first

gm queue list [OPTIONS]

R, --repo <repo>
--status <queued|merging|testing|advancing|landed|failed|cancelled|covered>

gm queue list
gm queue list --status failed -R owner/repo

gm queue show

Inspect an admission and its failure/deployment evidence

gm queue show [OPTIONS] <ID>

id: Required.
R, --repo <repo>

gm queue show COMMIT_ID

gm queue wait

Wait for landing; --deploy also requires the final main pipeline to succeed

gm queue wait [OPTIONS] <ID>

id: Required.
R, --repo <repo>
--timeout <timeout>: Default: 1800.
--deploy

gm queue wait COMMIT_ID --deploy --timeout 1800

gm queue cancelchanges state

Cancel pending work without rewinding main

gm queue cancel [OPTIONS] <ID>

id: Required.
R, --repo <repo>

gm queue cancel COMMIT_ID

gm queue retrychanges state

Retry a failed or cancelled admission of the same commit

gm queue retry [OPTIONS] <ID>

id: Required.
R, --repo <repo>

gm queue retry COMMIT_ID

gm timeline

gm timeline startchanges state

Start a timeline forked from main (or another timeline), then work in it here

gm timeline start [OPTIONS] <SLUG>

slug: Lowercase letters and digits joined by hyphens; work lives in an owned source Required.
--name <name>: A readable name (default: the slug)
--policy <auto|approval>: How it lands: auto (when gates pass) or approval (after a person approves)
--experimental: Mark it as not expected to land (a marker, not a restriction)
--from <from>: What it forks from: main, or another timeline's slug Default: main.
--repo <repo>…: Repositories it touches, owner/name (repeatable). Default: this checkout's repository, or the parent timeline's repositories with --from <timeline>
--no-use: Only create it; don't bind this checkout to it
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline start search-v2
gm timeline start search-v2 --policy approval --name "Search v2"
gm timeline start probe --experimental --from search-v2
gm timeline start shared --repo orbit/engine --repo orbit/web

gm timeline list

List the tracker's timelines, newest first

gm timeline list [OPTIONS]

--status <status>: Only timelines with this status (active, idle, waiting, landing, partly_landed, landed, abandoned)
--stalled: Only open timelines with no push for the account's idle period; experimental ones, which aren't expected to land, are left out
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline list
gm timeline list --status active
gm timeline list --stalled

gm timeline show

Show a timeline (default: this checkout's) and its events

gm timeline show [OPTIONS] [SLUG]

slug: The timeline's slug (default: the one this checkout works in)
--after <after>: Events after this sequence number (page with the `next` of the previous answer) Default: 0.
--limit <limit>: Events per page Default: 200.
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline show
gm timeline show search-v2 --after 40

gm timeline usechanges state

Work in a timeline here: pushes go to its bookmark, never to main (`use main` to go back)

Like git switch <branch> (and push there by default)

gm timeline use [OPTIONS] <SLUG>

slug: The timeline's slug, or `main` to stop working in a timeline Required.
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline use search-v2
gm timeline use main

gm timeline mergechanges state

Merge main or another timeline into this checkout's timeline, below the working copy

Like git merge --no-ff <exact source revision>

gm timeline merge [OPTIONS] <FROM>

from: `main`, or the slug of another timeline to bring into this one Required.
m, --message <message>…: Description for the merge (default "Merge <from> into timeline/<slug>")

gm timeline merge main
gm timeline merge search-v2

gm timeline abandonchanges state

End a timeline and archive its work sources; keep this checkout's push guard

gm timeline abandon [OPTIONS] [SLUG]

slug: The timeline's slug (default: the one this checkout works in)
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline abandon
gm timeline abandon probe --dry-run

gm timeline checkpointchanges state

Record a checkpoint: the timeline's pushed commits now, with a summary, for a person to approve

gm timeline checkpoint [OPTIONS] [SLUG]

slug: The timeline's slug (default: the one this checkout works in)
m, --message <message>…: Summary in Markdown: what it holds and why (repeat for paragraphs; '-' reads stdin, '@path' a file)
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline checkpoint -m 'Search v2 ranking is ready: …'
gm timeline checkpoint search-v2 -m @summary.md

gm timeline checkpoints

List a timeline's checkpoints, newest first, with CI runs, previews and approvals

gm timeline checkpoints [OPTIONS] [SLUG]

slug: The timeline's slug (default: the one this checkout works in)
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline checkpoints
gm timeline checkpoints search-v2

gm timeline revivechanges state

Revive a checkpoint's preview (default: the newest): rebuild it from its commits in CI

gm timeline revive [OPTIONS] [SLUG]

slug: The timeline's slug (default: the one this checkout works in)
c, --checkpoint <checkpoint>: The checkpoint: its number in the timeline or its id (default: the newest)
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline revive
gm timeline revive search-v2 --checkpoint 3
gm timeline revive search-v2 -c cp_…

gm timeline pageschanges state

The wiki pages a timeline affects, written at its checkpoints (or now, with --write)

gm timeline pages [OPTIONS] [SLUG]

slug: The timeline's slug (default: the one this checkout works in)
--checkpoint <checkpoint>: Only the pages written for this checkpoint (its number or id)
--write: Write the pages at each bookmark's tip now (uses AI; asking twice at one commit is one set)
--page <page>: Print one page in full, by its wiki slug (e.g. components/src-web or glossary)
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline pages
gm timeline pages search-v2 --checkpoint 2
gm timeline pages --page components/apps-website-worker-knowledge
gm timeline pages --write

gm timeline landchanges state

Land the approved source tree compactly onto main after gates pass

Like compact tree integration + CI + canonical compare-and-swap

gm timeline land [OPTIONS] [SLUG]

slug: The timeline's slug (default: the one this checkout works in)
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline land
gm timeline land search-v2

gm timeline updatechanges state

Rename a timeline (default: this checkout's), or flag it experimental or clear the flag

Like git branch -m (the name only)

gm timeline update [OPTIONS] [SLUG]

slug: The timeline's slug (default: the one this checkout works in)
--name <name>: A new readable name
--experimental: Mark it as not expected to land, so stalled views leave it out. A marker, not a restriction: its work still merges anywhere, and it can still land
--no-experimental: Clear the experimental flag
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline flag probe --experimental
gm timeline update probe --no-experimental
gm timeline update --name "Search v2"

gm timeline migratechanges state

Convert a legacy timeline to owned work sources; renew its checkpoint and approval afterward

gm timeline migrate [OPTIONS] [SLUG]

slug: Timeline slug (default: this checkout's)
--resolve <cancel-unadvanced|accept-partial-and-abandon>: Resolve a stopped legacy landing instead of converting; inspect `timeline show` first
--expected-version <expected-version>: Exact landing version observed by the operator; stale versions are rejected
--note <note>: Audit reason for resolving the legacy landing
O, --owner <owner>: Tracker account (default: .gitmatrix/agents.yml's, else origin's owner, else `gm tracker use`)

gm timeline migrate
gm timeline migrate search-v2
gm timeline migrate search-v2 --resolve cancel-unadvanced --expected-version 7 --note 'Stopped CI; no canonical advance'
gm timeline migrate search-v2 --resolve accept-partial-and-abandon --expected-version 9 --note 'Accept existing receipts; remaining work moves to a fresh timeline'

gm context

gm context syncchanges state

Upload step context the server doesn't have yet (after an offline push or a crash)

gm context sync

gm context sync

gm context show

The context of one step: why, instructions, steering, challenges, tests

gm context show [REVISION]

revision: Revision to show Default: @-.

gm context show
gm context show kxyz

gm test

Run this repository's fast checks: the step jobs in .gitmatrix/ci.yml marked local: true

gm test

gm test

gm step

gm stepchanges state

Record a step of a timeline: gm test, commit with context, push

Like git commit -am && git push

gm step [OPTIONS] --message <MESSAGE>

m, --message <message>…: Summary of the step: the commit's description Required.
--context <context>: The step's context: a JSON or Markdown file, or `-` for stdin, with instructions, steering, why and challenges (see `gm commit --context`)
--no-test: Don't run `gm test` first

gm step -m "Rank by recency" --context step.md
gm step -m "Docs" --no-test

gm steps

A timeline's steps in this repository; --follow streams new ones live

gm steps [OPTIONS]

--timeline <timeline>: The timeline (default: the one this checkout works in)
f, --follow: Stream new steps as they're pushed: one JSON object per line for agents, a line of text at a terminal. Reconnects on its own; Ctrl-C stops
--count <count>: With --follow: stop after this many steps
n, --limit <limit>: Without --follow: how many recent steps Default: 20.

gm steps
gm steps --follow
gm steps --timeline search-v2 --follow --count 1

gm hook

gm hookchanges state

Harness hooks (installed by `gm agent setup`); not for direct use

gm hook <HARNESS>

harness: The harness: claude-code, codex or pi (Oh My Pi) Required.

gm hook claude-code
gm hook codex
gm hook pi

gm auth

gm auth loginchanges state

Like git credential approve / ssh-add

gm auth login [OPTIONS]

--device: Approve this sign-in in the browser with a one-time code (the default without other flags)
--ssh: Sign in with an SSH key registered on the server, through your SSH agent or key files
--key <key>: With --ssh: the key to use (fingerprint, key file, or part of its comment)
--persona <persona>: Dev persona to mint a token for (priya, marco, jun, sam)
--token <token>: Existing personal access token (gmx_…)
--server <server>: Server URL; also makes it the default. GM_SERVER signs in to a server for this run without changing the default

gm auth login --ssh
gm auth login --ssh --key ~/.ssh/id_ed25519
gm auth login --persona jun
gm auth login --token gmx_...

gm auth ssh-key addchanges state

Like (GitHub: Settings > SSH keys)

gm auth ssh-key add [OPTIONS]

--key <key>: Which key: fingerprint, key file, or part of its comment (default: the first one found)
--title <title>: Name shown for the key (default: its comment)
--read-only: Sessions from this key can clone and fetch but not push

gm auth ssh-key add
gm auth ssh-key add --key SHA256:abc... --title Laptop

gm auth ssh-key list

Keys registered on the server, and the keys gm can use on this machine

Like ssh-add -l

gm auth ssh-key list

gm auth ssh-key list

gm auth ssh-key removechanges state

Unregister a key (by id or fingerprint); its sessions end at once

gm auth ssh-key remove <KEY>

key: Required.

gm auth ssh-key remove SHA256:abc...

gm auth git-credential

Git credential helper: lets plain git use your gm sign-in, SSH keys included

Like git credential-<helper>

gm auth git-credential <OPERATION>

operation: What git asks for: get, store or erase Required.

git config --global credential.https://git.example.com.helper '!gm auth git-credential'

gm auth status

Show who you are signed in as

gm auth status

gm auth status

gm auth logoutchanges state

Forget the stored token

Like git credential reject

gm auth logout

gm auth logout

gm settings

gm settings ai show

Show policy, published model catalog, gateway body logging and your management permission

gm settings ai show [OPTIONS]

--owner <owner>: Account slug; defaults to the signed-in person, never the repository owner
--site: The site's defaults instead (site administrators)

gm settings ai show
gm settings ai show --owner orbit
gm settings ai show --site

gm settings ai setchanges state

Change future jobs only; human account/org owner or site admin required

gm settings ai set [OPTIONS] <--knowledge <KNOWLEDGE>|--wiki <WIKI>|--atlas <ATLAS>|--release-notes <RELEASE_NOTES>|--classification <CLASSIFICATION>|--fast <FAST>|--task <TASK>|--knowledge-quiet-minutes <KNOWLEDGE_QUIET_MINUTES>|--knowledge-max-wait-minutes <KNOWLEDGE_MAX_WAIT_MINUTES>|--log-bodies <[COMPONENT=]on|off|default>>

--owner <owner>: Account slug; defaults to the signed-in person, never the repository owner
--site: Set the site's defaults (site administrators); only --log-bodies applies
--knowledge <on|off>: Knowledge ingestion and embeddings; off also prevents new wiki and Atlas AI work
--wiki <on|off>: Main wiki and timeline checkpoint pages (requires knowledge on)
--atlas <on|off>: Paid Atlas descriptions, not deterministic projection (requires knowledge on)
--release-notes <on|off>: Automatic release-note generation
--classification <classification>: Classification model: clef, or typesafe:<model> added in Settings → AI providers; see show for published pricing and release dates
--fast <fast>: Fast generation model: glm-5.3-flash, gemma-4-26b-a4b-it, or openrouter:<model> added in Settings → AI providers; see show for published pricing and release dates
--task <task>: Task generation model (as --fast); does not change running jobs or regenerate cached output
--knowledge-quiet-minutes <knowledge-quiet-minutes>: Knowledge updates start once pushes to main pause this long (0-1440 minutes; 0 = no wait)
--knowledge-max-wait-minutes <knowledge-max-wait-minutes>: …and never later than this after the first pending push (0-1440 minutes)
--log-bodies <log-bodies>…: Keep AI request and response bodies in gateway logs: on|off|default for every component, or COMPONENT=on|off|default (repeatable). default follows the site (with --site: the environment). While on, prompts and replies, including repository code and assistant conversations, are kept in Cloudflare's AI Gateway logs, readable in the Cloudflare dashboard, and deleted oldest-first

gm settings ai set --owner orbit --knowledge off --dry-run
gm settings ai set --site --log-bodies on
gm settings ai set --owner orbit --log-bodies assistant=off --log-bodies avatars=default
gm settings ai set --owner orbit --classification clef --fast glm-5.3-flash --task gemma-4-26b-a4b-it
gm settings ai set --owner orbit --knowledge-quiet-minutes 15 --knowledge-max-wait-minutes 60

gm retention

gm retention show

Categories with their scope, switch, effective thresholds (and where each comes from) and last run

gm retention show [OPTIONS] [CATEGORY]

category: Only this category (e.g. ci-logs)
--owner <owner>: Account slug; defaults to the signed-in person, never the repository owner
--site: The site level: site categories and site-wide defaults (site administrators)

gm retention show
gm retention show ci-logs --owner orbit
gm retention show --site

gm retention setchanges state

Enable, disable or reset a category, or change its thresholds (account owners or site administrators)

gm retention set [OPTIONS] <--enable|--disable|--inherit|--threshold <KEY=VALUE>|--reset <KEY>> <CATEGORY>

category: Category id, e.g. ci-logs (see `gm retention show`) Required.
--enable: Turn the category on: scheduled cleanups delete what its policy selects
--disable: Turn the category off at this level
--inherit: Remove this level's switch, so it inherits (site-wide default, then off)
--threshold <threshold>…: Set a threshold: key=value, a whole number (repeatable), e.g. days=60
--reset <reset>…: Remove this level's value for a threshold, so it inherits (repeatable)
--owner <owner>: Account slug; defaults to the signed-in person, never the repository owner
--site: The site level: site categories and site-wide defaults (site administrators)

gm retention set ci-logs --enable --owner orbit
gm retention set ci-runs --threshold days=90 --threshold keepLatest=10
gm retention set ci-logs --inherit --reset days
gm retention set registry-audit --enable --site

gm retention runchanges state

Clean up now: run categories (add --dry-run to preview what would be deleted), then wait for the result

gm retention run [OPTIONS] <CATEGORIES>...

categories: Category ids to clean up (any with a cleanup, enabled or not) Required.
--threshold <threshold>…: Override a threshold for this run only: category.key=value (repeatable), e.g. ci-logs.days=7
--yes: Required for a real run (not --dry-run): confirms deleting what the policy selects
--no-wait: Return the queued run at once instead of waiting for it to finish
--timeout <timeout>: Give up waiting after this many seconds (the run keeps going) Default: 900.
--owner <owner>: Account slug; defaults to the signed-in person, never the repository owner
--site: The site level: site categories and site-wide defaults (site administrators)

gm retention run ci-logs ci-runs --dry-run
gm retention run ci-logs --threshold ci-logs.days=14 --yes
gm retention run auth-hygiene --site --dry-run

gm retention runs

Cleanup run history, newest first, or one run with each category's counts

gm retention runs [OPTIONS] [ID]

id: One run's id; omit to list runs
--before <before>: List runs older than this id (the `next` of the previous page)
--limit <limit>: At most this many runs
--owner <owner>: Account slug; defaults to the signed-in person, never the repository owner
--site: The site level: site categories and site-wide defaults (site administrators)

gm retention runs
gm retention runs --site --limit 5
gm retention runs 12 --owner orbit

gm repo

gm repo list

List repositories you can read

gm repo list

gm repo list

gm repo createchanges state

Create a repository, empty or imported from a public Git URL

gm repo create [OPTIONS] <NAME>

name: Repository name Required.
--owner <owner>: Owner (you, or an org you belong to). Default: you
--description <description>
--public: Make it public (default private)
--import <import>: Import from this public https:// Git URL

gm repo create demo
gm repo create engine --owner orbit --import https://github.com/lukeed/clsx

gm repo view

Show a repository with its branches (default: the current one)

Like git remote show origin

gm repo view [REPOSITORY]

repository

gm repo view
gm repo view orbit/engine

gm repo deletechanges state

Delete a repository on the server, permanently

gm repo delete [OPTIONS] <REPOSITORY>

repository: Required.
--yes: Required: confirms the deletion

gm repo delete jun/demo --yes

gm repo mirror show

The repository's mirror and how its last sync went

gm repo mirror show [OPTIONS]

R, --repo <repo>

gm repo mirror show

gm repo mirror setchanges state

Create or change the mirror; the token comes from --token-stdin

Like git remote add --mirror=push

gm repo mirror set [OPTIONS] [URL]

url: HTTPS clone URL to push to, e.g. https://github.com/owner/name.git
R, --repo <repo>
--token-stdin: Read a token with push access from stdin (kept if omitted)
--username <username>: Username sent with the token (GitHub accepts any)
--prune: Also delete tags (and the default branch) on the target that are gone here
--no-prune
--disable: Pause mirroring without forgetting the settings
--enable

gh auth token | gm repo mirror set https://github.com/owner/name.git --token-stdin
gm repo mirror set --prune

gm repo mirror syncchanges state

Sync now and wait for the result

Like git push --mirror

gm repo mirror sync [OPTIONS]

R, --repo <repo>

gm repo mirror sync

gm repo mirror removechanges state

Stop mirroring (the target keeps what it has)

gm repo mirror remove [OPTIONS]

R, --repo <repo>

gm repo mirror remove

gm semantic

gm semantic list

One page of individual semantic changes, with source links and analysis coverage

gm semantic list [OPTIONS]

R, --repo <repo>: Repository as owner/name (default: this repository's origin)
--ref <ref>: Server branch or commit id (default: repository default branch)
--cursor <cursor>: Opaque nextCursor from the previous page; keep the same filters
n, --limit <limit>: Maximum entries in this page; empty pages may still have a nextCursor Default: 30.
--path <path>: Exact repository-relative file path
--kind <kind>: Exact change kind, e.g. symbol.added or symbol.signature_changed
--language <language>: Language: typescript, tsx, rust, python, go, markdown, xml, json, html, css

gm semantic list --repo orbit/engine -o json
gm semantic list --ref main --language rust --kind symbol.signature_changed
gm semantic list --path src/main.ts --cursor '<nextCursor>'

gm release

gm release list

Releases with notes: unreleased work first, then tags newest first

gm release list [OPTIONS]

R, --repo <repo>: Repository as owner/name (default: this repository's origin)

gm release list --repo orbit/engine

gm release notes

One release's notes (default: the newest release with entries)

gm release notes [OPTIONS] [RELEASE]

release: A tag, or `unreleased` for the default branch's work since the newest tag
R, --repo <repo>: Repository as owner/name (default: this repository's origin)
--internal: Include internal entries (chores, refactors, tests, tooling)

gm release notes
gm release notes v1.2.0 --repo orbit/engine
gm release notes day:2026-10-02 --internal -o json

gm release feed

A tracker account's notes across repositories, filtered by facets

gm release feed [OPTIONS] [QUERY]...

query: Filters and words, e.g. `type:fix repo:engine since:30d`; keys are team, repo, ws, type, label, release, since and until, negated with a leading `-`
--team <team>: Only this team's work (adds `team:KEY`)
--owner <owner>: Tracker account/organization slug; otherwise use saved tracker context
--internal: Include internal entries (chores, refactors, tests, tooling)

gm release feed --owner orbit
gm release feed --team CORE since:30d
gm release feed kind:tag repo:engine -o json
gm release feed release:day:2026-10-02

gm runs

gm runs list

Recent runs, newest first

gm runs list [OPTIONS]

R, --repo <repo>: Repository as owner/name (default: this repository's origin)
n, --limit <limit>: Default: 20.

gm runs list
gm runs list -R orbit/engine

gm runs show

One run with its jobs and steps (default: the latest run)

gm runs show [OPTIONS] [NUMBER]

number
R, --repo <repo>

gm runs show
gm runs show 12

gm runs logs

Output of a run's jobs (default: the latest run, every job)

gm runs logs [OPTIONS] [NUMBER]

number
j, --job <job>: Only this job
R, --repo <repo>
f, --follow: Keep streaming until the jobs finish (text output)

gm runs logs
gm runs logs 12 --job test
gm runs logs 12 -f

gm runs wait

Block until a run finishes; exits 0 only if it succeeded. Default: the run for trunk

gm runs wait [OPTIONS] [NUMBER]

number: Run number. Default: the newest run for --commit
c, --commit <commit>: Revision or commit hash whose run to wait for (default `trunk`)
R, --repo <repo>
--timeout <timeout>: Give up after this many seconds Default: 1800.

gm runs wait
gm push && gm runs wait
gm runs wait 12
gm runs wait --commit @-

gm runs startchanges state

Start a run of a branch by hand

gm runs start [OPTIONS]

--ref <ref>: Branch (default: the repository's default branch)
R, --repo <repo>

gm runs start
gm runs start --ref feature-x

gm runs cancelchanges state

Cancel a queued or running run

gm runs cancel [OPTIONS] <NUMBER>

number: Required.
R, --repo <repo>

gm runs cancel 12

gm runs rerunchanges state

Run the same commit again

gm runs rerun [OPTIONS] <NUMBER>

number: Required.
R, --repo <repo>

gm runs rerun 12

gm runner

Run queued CI jobs on this machine (how CI runs against the dev server)

gm runner [OPTIONS]

R, --repo <repo>: Only take jobs from this repository (owner/name)
--name <name>: Name shown on the jobs this runner takes (default: the host name)
--once: Take at most one job, then exit (exits right away when none is queued)
--poll <poll>: Seconds between polls for work Default: 2.
--workdir <workdir>: Where jobs check out code (default: ~/.cache/gitmatrix/runner)
v, --verbose: Echo job output here as well as to the server

gm runner
gm runner --once
gm runner -R orbit/engine -v

gm deploy

gm deploy recordchanges state

Record a deployment: where a commit is deployed (from a CI job, or with --commit)

gm deploy record [OPTIONS]

--url <url>: Where the deployment answers (http or https). Only a failed deployment may omit it
e, --environment <environment>: Environment: `production`, `timeline/<slug>`, `branch/<name>` or a name of your own. Default: the timeline's; in CI, from the branch (default branch: production; timeline/<slug>: its timeline; any other: branch/<name>, lowercased); otherwise production
--timeline <timeline>: Timeline slug (default: $GITMATRIX_TIMELINE)
--checkpoint <checkpoint>: Checkpoint id (default: $GITMATRIX_CHECKPOINT)
--status <active|sleeping|expired|failed>: Status (default: active)
--expires <expires>: When the deployment expires: an ISO time, a duration from now (`30m`, `12h`, `2d`), or `never`. Default: none, except timeline previews (the account's idle period)
c, --commit <commit>: Deployed revision or full commit hash (default in CI: the job's commit). Required outside CI
R, --repo <repo>: Repository as owner/name (default: $GITMATRIX_REPOSITORY, then this repository's origin)

gm deploy record --url "$PREVIEW_URL"
gm deploy record --url https://app.example.com --environment production --commit @-
gm deploy record --status failed --timeline fast-search

gm deploy list

Deployments, newest first, filtered by environment, timeline, commit, run or status

gm deploy list [OPTIONS]

e, --environment <environment>
--timeline <timeline>: Timeline slug
c, --commit <commit>: Revision or full commit hash
--run <run>: CI run number
--status <active|sleeping|expired|failed>
n, --limit <limit>: Default: 20.
R, --repo <repo>

gm deploy list
gm deploy list --timeline fast-search
gm deploy list --run 12
gm deploy list --environment production --status active

gm deploy updatechanges state

Change a deployment's status, URL or expiry (e.g. mark a torn-down preview expired)

gm deploy update [OPTIONS] <ID>

id: Deployment id (from `gm deploy record` or `gm deploy list`) Required.
--status <active|sleeping|expired|failed>
--url <url>: New URL, or an empty string to clear it (failed deployments only)
--expires <expires>: An ISO time, a duration from now (`2d`), or `never`
R, --repo <repo>

gm deploy update 42 --status expired
gm deploy update 42 --expires 2d

gm secret

gm secret list

Secret names (values are never shown)

gm secret list [OPTIONS]

R, --repo <repo>

gm secret list

gm secret setchanges state

Create or replace a secret; the value comes from --value or stdin

gm secret set [OPTIONS] <NAME>

name: Required.
--value <value>
R, --repo <repo>

gm secret set NPM_TOKEN --value xyz
echo $TOKEN | gm secret set CLOUDFLARE_API_TOKEN

gm secret deletechanges state

Remove a secret

gm secret delete [OPTIONS] <NAME>

name: Required.
R, --repo <repo>

gm secret delete NPM_TOKEN

gm agent

gm agent setupchanges state

Set up this checkout for a coding agent: instructions, skills, identity and profile. Rerun to update

gm agent setup [OPTIONS]

--name <name>: Agent name (default: a memorable generated name; kept on reruns)
--harness <harness>: claude-code, codex, cursor-agent, gemini-agent, opencode…; detected when an agent runs this
--model <model>: The model it runs (never inferred)
--tag <tag>…: Add a profile tag (repeat)
--drop-tag <drop-tag>…: Remove a profile tag (repeat)
--owner <owner>: Tracker owner; seeds .gitmatrix/agents.yml (default: origin's owner)
--team <team>: Team `gm issue next` picks from
--under <under>: Only work under this issue, e.g. a project
--ttl <ttl>: Lease seconds
--intervention <intervention>: Human intervention: autonomous records requests and continues scoped work; harness keeps its own behavior. New projects default to autonomous; existing projects save an override for this checkout
--no-identity: Only write the files; don't create the agent, keep a token or publish its profile
--check: Report what's out of date without changing anything (exit 4 if stale)
--publish-skills <publish-skills>: Which discovered skills its profile publishes: repo (default), all (adds your user-level skills) or none; saved for this checkout
--allow-skill <allow-skill>…: Publish this skill whatever the scope (repeat; saved)
--deny-skill <deny-skill>…: Never publish this skill (repeat; saved)

gm agent setup
gm agent setup --intervention autonomous
gm agent setup --intervention harness
gm agent setup --harness codex --model gpt-5 --tag rust
gm agent setup --under CORE-4
gm agent setup --check

gm agent modchanges state

Install the Claude Code mod: a card above the prompt with the gitmatrix issue the session works on, toggled by ctrl+x g or /gm-work. Rerun to update

gm agent mod [OPTIONS]

--key <key>: The chord that toggles the card (default: the one already bound, else ctrl+x g)
--check: Report what's out of date without changing anything (exit 4 if stale)
--remove: Uninstall the mod and its keybinding

gm agent mod
gm agent mod --key 'ctrl+x w'
gm agent mod --check
gm agent mod --remove

gm agent list

Your agents and advisory capabilities, optionally from an owner's tracker

gm agent list [OPTIONS]

--owner <owner>

gm agent list
gm agent list --owner orbit

gm agent detect

Detect local advisory capabilities without network access

gm agent detect [OPTIONS]

--harness <harness>: Explicit harness identifier (otherwise detected)
--clear-harness
--model <model>: Explicit model identifier; never inferred from harness
--clear-model
--runtime <host|container|vm|wsl|cloudflare-worker|unknown>: Override detected runtime classification
--tag <tag>…: Replace tags with this repeatable set
--clear-tags
--skill <skill>…: Replace declared skills with NAME or NAME=DESCRIPTION (repeatable)
--clear-skills: Remove declared skills; detected skills are still refreshed
--skill-dir <skill-dir>…: Additional directory containing skill directories or a SKILL.md (always published)
--publish-skills <publish-skills>: Which discovered skills to publish: repo (default), all (adds your user-level skills) or none; otherwise .gitmatrix/agent.local.yml's skills.publish
--allow-skill <allow-skill>…: Publish this skill whatever the scope (repeat)
--deny-skill <deny-skill>…: Never publish this skill (repeat)

gm agent detect
gm agent detect --model explicit-model --tag rust

gm agent configurechanges state

Create or refresh a named owned agent, or the authenticated agent itself

gm agent configure [OPTIONS] [NAME]

name
--harness <harness>: Explicit harness identifier (otherwise detected)
--clear-harness
--model <model>: Explicit model identifier; never inferred from harness
--clear-model
--runtime <host|container|vm|wsl|cloudflare-worker|unknown>: Override detected runtime classification
--tag <tag>…: Replace tags with this repeatable set
--clear-tags
--skill <skill>…: Replace declared skills with NAME or NAME=DESCRIPTION (repeatable)
--clear-skills: Remove declared skills; detected skills are still refreshed
--skill-dir <skill-dir>…: Additional directory containing skill directories or a SKILL.md (always published)
--publish-skills <publish-skills>: Which discovered skills to publish: repo (default), all (adds your user-level skills) or none; otherwise .gitmatrix/agent.local.yml's skills.publish
--allow-skill <allow-skill>…: Publish this skill whatever the scope (repeat)
--deny-skill <deny-skill>…: Never publish this skill (repeat)

gm agent configure builder --tag rust --skill review
gm agent configure
gm agent configure builder --clear-model --clear-tags --clear-skills --dry-run

gm agent show

Show a named owned agent, or the authenticated agent itself

gm agent show [NAME]

name

gm agent show builder
gm agent show

gm agent createchanges state

Create an agent accountable to you

gm agent create [OPTIONS] <NAME>

name: Lowercase letters, digits and hyphens, e.g. builder Required.
--description <description>

gm agent create builder --description "Works the CORE graph"

gm agent tokenchanges state

Mint a token the agent signs in with (shown once)

gm agent token [OPTIONS] <NAME>

name: The agent's name or id Required.
--name <name>: What to call the token
--scope <scope>: read or write Default: write.

gm agent token builder

gm agent revokechanges state

Revoke an agent; its tokens stop working at once

gm agent revoke <NAME>

name: The agent's name or id Required.

gm agent revoke builder

gm ask

Ask the Gitmatrix assistant about code, issues, CI and packages (read-only unless --write)

gm ask [OPTIONS] <QUESTION>...

question: The question; '-' reads it from stdin Required.
R, --repo <repo>: owner/name it's about; defaults to this checkout's repository
--chat <chat>: Continue a conversation (an id from the last answer or `gm assistant list`)
--write: Let the assistant make changes (create issues, comment, rerun CI…) without asking

gm ask "Why did run 44 fail?"
gm ask -R matrixorg/gitmatrix "Where is the tracker's readiness computed?"
gm ask --chat CHAT_ID "And who changed it last?"
gm ask --write "File a bug for the flaky clone test in CORE"

gm assistant

gm assistant list

Your conversations, newest first

gm assistant list

gm assistant list

gm assistant show

A conversation's messages and what the assistant did

gm assistant show <ID>

id: Required.

gm assistant show CHAT_ID

gm assistant deletechanges state

Delete a conversation

gm assistant delete <ID>

id: Required.

gm assistant delete CHAT_ID

gm pkg

gm pkg list

An owner's packages, most recently published first

gm pkg list [OPTIONS]

O, --owner <owner>: Owner (user or org). Default: this repository's owner, else you

gm pkg list
gm pkg list -O orbit

gm pkg show

One package: latest version, tags, sources, counts and the install command

gm pkg show [OPTIONS] <PACKAGE>

package: Required.
O, --owner <owner>

gm pkg show npm/@orbit/web
gm pkg show oci/engine

gm pkg versions

A package's publishes, newest first, filtered by a query

gm pkg versions [OPTIONS] <PACKAGE>

package: Required.
q, --query <query>: source:web branch:main status:active since:7d commit:ab12 run:42 by:jun tag:latest; words match versions; - excludes Default: status:active.
n, --limit <limit>: Default: 50.
--offset <offset>: Default: 0.
O, --owner <owner>

gm pkg versions npm/@orbit/web
gm pkg versions oci/engine -q "branch:main since:24h"
gm pkg versions npm/@orbit/web -q "commit:4f2a1b"

gm pkg deletechanges state

Delete versions (owner admins); name them, or select them with --query

gm pkg delete [OPTIONS] <PACKAGE> [VERSIONS]...

package: Required.
versions: Versions to act on
q, --query <query>: Everything this query matches instead (up to 1,000 per call)
--reason <reason>: Why (shown to npm users on deprecation; recorded on yanks)
O, --owner <owner>

gm pkg delete npm/@orbit/web 1.0.0-pr.12
gm pkg delete oci/engine -q "branch:feature/* since:90d" --dry-run

gm pkg yankchanges state

Yank versions (Cargo, PyPI): still resolvable when pinned, never chosen

gm pkg yank [OPTIONS] <PACKAGE> [VERSIONS]...

package: Required.
versions: Versions to act on
q, --query <query>: Everything this query matches instead (up to 1,000 per call)
--reason <reason>: Why (shown to npm users on deprecation; recorded on yanks)
O, --owner <owner>

gm pkg yank cargo/orbit-core 0.4.1 --reason "breaks serde"

gm pkg restorechanges state

Undo a yank or a deprecation

gm pkg restore [OPTIONS] <PACKAGE> [VERSIONS]...

package: Required.
versions: Versions to act on
q, --query <query>: Everything this query matches instead (up to 1,000 per call)
--reason <reason>: Why (shown to npm users on deprecation; recorded on yanks)
O, --owner <owner>

gm pkg restore cargo/orbit-core 0.4.1

gm pkg deprecatechanges state

Deprecate npm versions with a message

gm pkg deprecate [OPTIONS] <PACKAGE> [VERSIONS]...

package: Required.
versions: Versions to act on
q, --query <query>: Everything this query matches instead (up to 1,000 per call)
--reason <reason>: Why (shown to npm users on deprecation; recorded on yanks)
O, --owner <owner>

gm pkg deprecate npm/@orbit/web 1.x --reason "Use 2.x"

gm pkg tagchanges state

Point a tag at a version (npm dist-tag, Docker tag)

gm pkg tag [OPTIONS] <PACKAGE> <VERSION> <TAG>

package: Required.
version: Required.
tag: Required.
O, --owner <owner>

gm pkg tag npm/@orbit/web 2.4.0 stable
gm pkg tag oci/engine sha-4f2a1b7 prod

gm pkg sources

Repositories allowed to publish a package

gm pkg sources [OPTIONS] <PACKAGE>

package: Required.
O, --owner <owner>

gm pkg sources npm/@orbit/web

gm pkg grantchanges state

Allow a repository (owner/name) to publish a package

gm pkg grant [OPTIONS] <PACKAGE> <REPO>

package: Required.
repo: Required.
O, --owner <owner>

gm pkg grant npm/@orbit/web orbit/website

gm pkg revokechanges state

Stop a repository publishing a package

gm pkg revoke [OPTIONS] <PACKAGE> <REPO>

package: Required.
repo: Required.
O, --owner <owner>

gm pkg revoke npm/@orbit/web orbit/website

gm pkg published

What a CI run or a commit published (default: the latest run)

gm pkg published [OPTIONS]

--run <run>: Run number
--commit <commit>: Full commit hash
R, --repo <repo>

gm pkg published
gm pkg published --run 42
gm pkg published --commit $(git rev-parse HEAD)

gm pkg uploadchanges state

Upload a file as a generic package: gm pkg upload dist/app.tgz app/1.4.0

gm pkg upload [OPTIONS] <FILE> <TARGET>

file: Required.
target: <name>/<version>[/<path>]; the file name is used when no path is given Required.
O, --owner <owner>

gm pkg upload dist/app.tgz app/1.4.0
gm pkg upload build.zip app/$GITMATRIX_COMMIT/build.zip

gm pkg downloadchanges state

Download a generic artifact, verifying its SHA-256 before saving

gm pkg download [OPTIONS] <TARGET>

target: <name>/<version>/<path>; use latest to resolve the newest published version Required.
O, --owner <owner>
--dest <dest>: Destination file (default: the artifact's basename)
--force: Atomically replace an existing regular file

gm pkg download gm/latest/linux-x86_64/gm -O orbit --dest ./gm
gm pkg download app/1.4.0/app.tgz

gm pkg installchanges state

Install a Unix CLI artifact into ~/.local/bin (no installer scripts or archives)

gm pkg install [OPTIONS] <NAME>

name: Generic package and installed executable name Required.
O, --owner <owner>
--version <version>: Default: latest.
--file <file>: Artifact path within the version (default: <os>-<arch>/<name>)
--bin-dir <bin-dir>
--force: Atomically replace an existing executable, including this running gm

gm pkg install gm -O orbit
gm pkg install gm -O orbit --force
gm pkg install gm -O orbit --version <commit> --bin-dir ./bin

gm pkg setupchanges state

Configure npm, Docker, pip, Cargo… on this machine for an owner's registries

gm pkg setup [OPTIONS]

O, --owner <owner>
--write <write>…: Also write it: npm (~/.npmrc) and docker (docker login)

gm pkg setup
gm pkg setup -O orbit --write npm,docker

gm api

gm apichanges state

Call the Gitmatrix JSON API directly

gm api [OPTIONS] <METHOD> <PATH>

method: HTTP method Required.
path: Path under /api, e.g. /repos Required.
d, --data <data>: JSON request body

gm api GET /repos
gm api POST /repos -d '{"owner":"jun","name":"x","visibility":"private"}'

gm cli

gm cli search

Find commands by describing what you want to do

gm cli search [QUERY]...

query: What you want to do, in plain words

gm cli search "undo my last commit"

gm cli guide

The gm workflow in one page, for agents and AGENTS.md

gm cli guide

gm cli guide

gm cli commands

Every command with its arguments, as JSON

gm cli commands

gm cli commands

gm schema

Exact inputs and JSON output shape of a command

gm schema <COMMAND>...

command: Command path, e.g. `push` or `bookmark set` Required.

gm schema push
gm schema bookmark set

Global options

These work with every command.

o, --output <json|pretty|text>: Output format. Defaults to json for agents and pipes, text at a terminal
--dry-run: Show what a mutating command would do without changing anything
C, --cwd <cwd>: Run as if gm was started in this directory