CLI reference¶

Exit codes (stable, safe for scripts and agents to rely on):

code	meaning
0	success
1	error (bad input, missing object, I/O, ...); message on stderr
2	usage error (unknown command or option)
3	blocked: something you can provide is missing (approval, validation, lease token)
4	refused: conflict, policy denial or invalid request; the stream was not changed

Which commands use 3 and 4, and the commands that exit 1 on a problem they found, are listed in Help topics (ag help exit-codes).

Global options: -C/--repo, --as <identity> (or AG_IDENTITY), --json, --color <auto|always|never> (NO_COLOR is honoured; nothing is coloured in a pipe), -q/--quiet, -v/--verbose. Concept pages are available in the terminal: ag help workflow|policy|leases|identities|revisions|exit-codes|json|config, and in Help topics. Machine-readable output: --json shapes. Environment and files: Configuration. Shell completion and man pages: Completions and man pages.

Commands¶

ag
ag init
ag status
ag snapshot
ag sync
ag log
ag show
ag diff
ag cat
ag blame
ag ls
ag checkout
ag portability
ag stream
ag stream list
ag stream create
ag stream show
ag stream reflog
ag propose
ag proposal
ag proposal list
ag proposal show
ag proposal review
ag proposal update
ag proposal close
ag integrate
ag preview
ag explain
ag op
ag op show
ag op resume
ag op list
ag recover
ag queue
ag queue add
ag queue list
ag queue run
ag policy
ag policy show
ag policy set
ag policy history
ag policy example
ag policy preset
ag policy preset list
ag policy preset show
ag policy preset apply
ag policy explain
ag validate
ag validate keygen
ag validate run
ag validate list
ag agent
ag agent register
ag agent list
ag agent start
ag agent finish
ag agent heartbeat
ag agent runs
ag agent reap
ag agent disable
ag agent enable
ag task
ag task create
ag task list
ag task depend
ag task ready
ag task done
ag task cancel
ag lease
ag lease acquire
ag lease release
ag lease extend
ag lease list
ag provenance
ag provenance attach
ag provenance show
ag predict
ag workspace
ag workspace create
ag workspace list
ag workspace remove
ag trace
ag audit
ag verify
ag gc
ag reindex
ag backup
ag git
ag git import
ag git export
ag clone
ag fetch
ag pull
ag push
ag remote
ag remote add
ag remote list
ag remote remove
ag remote whoami
ag remote proposals
ag remote proposal
ag remote prepare
ag remote review
ag remote integrate
ag remote close
ag remote streams
ag remote events
ag remote policy
ag remote log
ag remote blame
ag remote cat
ag login
ag logout
ag pin
ag unpin
ag pins
ag doctor
ag config
ag config list
ag config get
ag config set
ag config unset
ag config path
ag completions
ag man
ag version

ag¶

AgentGit: an agent-native source control system. People, agents and CI change one codebase at the same time; every change lands through a proposal, and a per-stream policy decides what must be true first (validation of the exact tree, approvals, leases, an autonomy envelope for agents).

Usage: ag [OPTIONS] <COMMAND>

Commands:
  init         Create a repository in the current directory
  status       Summarize the workspace, your proposals, leases, task and remote at a glance
  snapshot     Record the working directory as a new snapshot
  sync         Bring the stream's latest head into the workspace
  log          Show history
  show         Show one changeset and what it changed
  diff         Show differences between two revisions, or the working directory and its snapshot
  cat          Print a file as of a revision: `ag cat main:src/lib.rs`
  blame        Show which changeset introduced each line of a file
  ls           List a directory as of a revision
  checkout     Write a revision's files into a new directory
  portability  List what a revision contains that Windows, macOS or Linux file systems cannot hold
  stream       Manage streams
  propose      Publish a snapshot and open a proposal to integrate it
  proposal     List, review, update or close proposals
  integrate    Integrate a proposal into its stream
  preview      Show what integrating a proposal would do, without doing it
  explain      Say why a proposal does not land yet, in plain words, with the exact commands that fix each reason
  op           Inspect or resume operations
  recover      Resume interrupted operations and expire stale ones
  queue        The ordered integration queue
  policy       Show or change stream policy
  validate     Run checks and issue signed attestations
  agent        Agent identities and runs
  task         Tasks and their dependencies
  lease        Soft and exclusive leases with fencing tokens
  provenance   Signed provenance of agent-made changes
  predict      Predict overlapping work
  workspace    Create, list and remove workspaces (isolated lines of work in their own directories)
  trace        Show the audit trail of an object, proposal, run or stream
  audit        Verify the tamper-evident audit chain
  verify       Check the integrity of the whole repository
  gc           Delete unreachable objects (safe: fails closed, honours a grace period)
  reindex      Rebuild derived indexes from the object store
  backup       Write a verified, consistent copy of the repository to a new directory
  git          Import from or export to Git (needs the `git` command)
  clone        Clone a repository from an `ag-server`
  fetch        Download new history from the server
  pull         Fetch, then fast-forward the local stream and bring the workspace up to date
  push         Upload your snapshot and open a proposal on the server
  remote       Manage remotes and work with proposals, events and policy on a server
  login        Save a server credential once; `clone`, `fetch`, `push` and `remote` then need no token plumbing
  logout       Forget a saved server credential
  pin          Pin a revision so garbage collection keeps it
  unpin        Remove a pin
  pins         List pins
  doctor       Check the installation, the repository, your identity and every remote's credential
  config       Show, get, set and locate configuration (the user file; the repository's settings are shown read-only)
  completions  Print a shell completion script: bash, zsh, fish, powershell or elvish
  man          Print the man page, or write one page per command with --dir
  version      Print the version, the protocol and the JSON schema version
  help         Show help for a command, or a topic: workflow, policy, leases, identities, revisions, exit-codes, json, config

Options:
  -C, --repo <DIR>
          Operate on the repository at this path (default: discovered from the current directory)

      --as <IDENTITY>
          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY

      --json
          Machine-readable JSON output

      --color <WHEN>
          Colour the output: auto (a terminal, unless NO_COLOR is set), always or never

  -q, --quiet
          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown

  -v, --verbose
          Explain what is happening on standard error: repository, identity, remote, timing

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Common workflow:
  ag init --namespace me/app     create a repository in this directory
  ag snapshot -m "message"       record the working directory
  ag propose -t "title"          publish it and open a proposal
  ag integrate PROPOSAL          land it (policy decides; any unique id prefix works)
  ag explain [PROPOSAL]          if it does not land: why, and the exact commands that fix it

Where am I, is it healthy:
  ag status                      workspace, your proposals, leases, task and remote at a glance
  ag doctor                      check the installation, the repository, your identity and every remote

Exit codes: 0 ok, 1 error, 2 usage, 3 blocked (provide what is missing and run it again),
4 refused (conflict, policy denial; the stream was not changed). Add --json for machine-readable output.

Help topics (ag help TOPIC): workflow, policy, leases, identities, revisions, exit-codes, json, config
Shell completion: ag completions bash|zsh|fish|powershell|elvish     Man pages: ag man --dir DIR
Documentation: https://github.com/Paffin/AgentGit/tree/main/docs

ag init¶

Create a repository in the current directory

Usage: ag init [OPTIONS]

Options:
  -C, --repo <DIR>             Operate on the repository at this path (default: discovered from the current directory)
      --namespace <NAMESPACE>  Repository namespace, e.g. `acme/webapp` (default: `local/<directory name>`)
      --as <IDENTITY>          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --stream <STREAM>        Name of the first stream [default: main]
      --json                   Machine-readable JSON output
      --storage <FILE>         JSON file with the `storage` section (PostgreSQL metadata and/or S3 objects); see docs/operations/postgres-and-s3.md. Default: a SQLite file and local objects under `.ag/`
      --color <WHEN>           Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
      --preset <NAME>          Store a ready-made policy for the first stream: solo, team, agents or strict (`ag policy preset list`)
      --admin <IDENTITY>       Identity pattern allowed to change the policy (repeatable). Default: you
  -q, --quiet                  Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
      --issuer <IDENTITY=KEY>  Trust this CI issuer to sign the `tests` check: IDENTITY=PUBLIC_KEY, e.g. service:ci=<64 hex digits>
  -v, --verbose                Explain what is happening on standard error: repository, identity, remote, timing
      --ci-key <NAME>          Trust the signing key NAME of this repository (created if missing; `ag validate keygen NAME` makes the same key): the issuer becomes service:NAME
  -h, --help                   Print help
  -V, --version                Print version

ag status¶

Summarize the workspace, your proposals, leases, task and remote at a glance

Usage: ag status [OPTIONS]

Options:
  -C, --repo <DIR>             Operate on the repository at this path (default: discovered from the current directory)
  -w, --workspace <WORKSPACE>  Workspace name [default: default]
      --as <IDENTITY>          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --dir <DIR>              Working directory of the workspace (required for non-default workspaces)
      --json                   Machine-readable JSON output
      --remote                 Also ask each remote's server for its current head (needs the network and a credential)
      --color <WHEN>           Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet                  Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                   Print help
  -V, --version                Print version

ag snapshot¶

Record the working directory as a new snapshot

Usage: ag snapshot [OPTIONS] --message <MESSAGE>

Options:
  -C, --repo <DIR>             Operate on the repository at this path (default: discovered from the current directory)
  -m, --message <MESSAGE>      Snapshot message
      --as <IDENTITY>          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
  -w, --workspace <WORKSPACE>  Workspace name [default: default]
      --dir <DIR>              Working directory of the workspace
      --json                   Machine-readable JSON output
      --color <WHEN>           Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
      --force                  Snapshot even if conflict markers remain
  -q, --quiet                  Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                   Print help
  -V, --version                Print version

ag sync¶

Bring the stream's latest head into the workspace

Usage: ag sync [OPTIONS]

Options:
  -C, --repo <DIR>             Operate on the repository at this path (default: discovered from the current directory)
  -w, --workspace <WORKSPACE>  Workspace name [default: default]
      --as <IDENTITY>          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --dir <DIR>              Working directory of the workspace
      --json                   Machine-readable JSON output
      --color <WHEN>           Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet                  Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                   Print help
  -V, --version                Print version

ag log¶

Show history

Usage: ag log [OPTIONS] [REV]

Arguments:
  [REV]  Revision to start from (default: the workspace head)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
  -n, --limit <LIMIT>  Maximum number of entries [default: 20]
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --path <PATH>    Only changesets that touched this path
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag show¶

Show one changeset and what it changed

Usage: ag show [OPTIONS] [REV]

Arguments:
  [REV]  Revision (default: the workspace head)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --copies         Also report files created as copies of another file (`C` lines): identical content, or at least 50% of the bytes in common with another file (co-modified and neighbouring files are tried first)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag diff¶

Show differences between two revisions, or the working directory and its snapshot

Usage: ag diff [OPTIONS] [REVS]...

Arguments:
  [REVS]...  With two revisions: diff A to B. With one: diff it against its first parent. With none: diff the workspace head against the working directory

Options:
  -C, --repo <DIR>             Operate on the repository at this path (default: discovered from the current directory)
  -U, --context <CONTEXT>      Lines of context [default: 3]
      --as <IDENTITY>          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
  -w, --workspace <WORKSPACE>  Workspace (for the no-argument form) [default: default]
      --dir <DIR>              Workspace directory (for the no-argument form)
      --json                   Machine-readable JSON output
      --color <WHEN>           Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet                  Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                   Print help
  -V, --version                Print version

ag cat¶

Print a file as of a revision: `ag cat main:src/lib.rs`

Usage: ag cat [OPTIONS] <SPEC>

Arguments:
  <SPEC>  `REV:PATH`, for example `main:src/lib.rs` or `@:README.md`

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag blame¶

Show which changeset introduced each line of a file

Usage: ag blame [OPTIONS] <SPEC>

Arguments:
  <SPEC>  `[REV:]PATH`, for example `src/lib.rs`, `main:src/lib.rs` or `@:README.md`. Without a revision, the workspace head (or the default stream) is used

Options:
  -C, --repo <DIR>                 Operate on the repository at this path (default: discovered from the current directory)
  -L, --lines <START,END>          Only these lines, `START,END` (1-based, inclusive)
      --as <IDENTITY>              Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --max-commits <MAX_COMMITS>  Visit at most this many changesets; older lines are marked as a boundary [default: 100000]
      --copies                     Follow files that were created as copies of another file: lines a copy took over are blamed on whoever wrote them in the source (identical content, or at least 50% of the bytes in common with a neighbouring or co-modified file)
      --json                       Machine-readable JSON output
      --color <WHEN>               Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet                      Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                    Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                       Print help
  -V, --version                    Print version

ag ls¶

List a directory as of a revision

Usage: ag ls [OPTIONS] [REV] [PATH]

Arguments:
  [REV]   Revision (default: the workspace head)
  [PATH]  Directory to list (default: the root)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag checkout¶

Write a revision's files into a new directory

Usage: ag checkout [OPTIONS] <REV> <DIR>

Arguments:
  <REV>  Revision to write out
  <DIR>  Destination directory (created if missing; must be empty)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag portability¶

List what a revision contains that Windows, macOS or Linux file systems cannot hold

Usage: ag portability [OPTIONS] [REV]

Arguments:
  [REV]  Revision to inspect (default: the workspace head) [default: @]

Options:
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
      --target <PLATFORM>  File system to check against: `windows`, `macos` or `linux` (default: this machine)
      --as <IDENTITY>      Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json               Machine-readable JSON output
      --color <WHEN>       Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet              Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose            Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help               Print help
  -V, --version            Print version

ag stream¶

Manage streams

Usage: ag stream [OPTIONS] <COMMAND>

Commands:
  list    List streams and their heads
  create  Create a stream, optionally at an existing published revision
  show    Show one stream
  reflog  Show the append-only history of head movements

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag stream list¶

List streams and their heads

Usage: ag stream list [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag stream create¶

Create a stream, optionally at an existing published revision

Usage: ag stream create [OPTIONS] <NAME>

Arguments:
  <NAME>  Stream name

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --from <FROM>    Start the stream at this published revision
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag stream show¶

Show one stream

Usage: ag stream show [OPTIONS] <NAME>

Arguments:
  <NAME>  Stream name

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag stream reflog¶

Show the append-only history of head movements

Usage: ag stream reflog [OPTIONS] <NAME>

Arguments:
  <NAME>  Stream name

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
  -n, --limit <LIMIT>  Maximum entries [default: 20]
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag propose¶

Publish a snapshot and open a proposal to integrate it

Usage: ag propose [OPTIONS] --title <TITLE> [REV]

Arguments:
  [REV]  Revision to propose (default: the workspace head)

Options:
  -C, --repo <DIR>                 Operate on the repository at this path (default: discovered from the current directory)
  -t, --title <TITLE>              Proposal title
      --as <IDENTITY>              Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
  -d, --description <DESCRIPTION>  Longer description [default: ""]
      --json                       Machine-readable JSON output
      --stream <STREAM>            Target stream (default: the repository's default stream)
      --color <WHEN>               Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
      --task <TASK>                Task this proposal belongs to
  -q, --quiet                      Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                    Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                       Print help
  -V, --version                    Print version

Examples:
  ag propose -t "Fix the parser"            propose the workspace head
  ag propose @docs -t "Document usage"      propose the head of workspace 'docs'
  ag propose --task task_… -t "…"           attach the proposal to a task

ag proposal¶

List, review, update or close proposals

Usage: ag proposal [OPTIONS] <COMMAND>

Commands:
  list    List proposals, newest first
  show    Show a proposal with its reviews
  review  Review the proposal's current head
  update  Point the proposal at a new head (earlier approvals stop counting)
  close   Close without integrating

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag proposal list¶

List proposals, newest first

Usage: ag proposal list [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --state <STATE>  Filter by state: open, integrated, closed
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
  -n, --limit <LIMIT>  Show at most this many (0 = all) [default: 200]
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag proposal show¶

Show a proposal with its reviews

Usage: ag proposal show [OPTIONS] <ID>

Arguments:
  <ID>  Proposal id

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag proposal review¶

Review the proposal's current head

Usage: ag proposal review [OPTIONS] <ID>

Arguments:
  <ID>  Proposal id

Options:
      --approve            Approve
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>      Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --request-changes    Request changes
      --comment            Comment only
      --json               Machine-readable JSON output
      --color <WHEN>       Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -m, --message <MESSAGE>  Review text [default: ""]
  -q, --quiet              Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose            Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help               Print help
  -V, --version            Print version

ag proposal update¶

Point the proposal at a new head (earlier approvals stop counting)

Usage: ag proposal update [OPTIONS] <ID> [REV]

Arguments:
  <ID>   Proposal id
  [REV]  New head (default: the workspace head)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag proposal close¶

Close without integrating

Usage: ag proposal close [OPTIONS] <ID>

Arguments:
  <ID>  Proposal id

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag integrate¶

Integrate a proposal into its stream

Usage: ag integrate [OPTIONS] <PROPOSAL>

Arguments:
  <PROPOSAL>  Proposal id

Options:
  -C, --repo <DIR>                      Operate on the repository at this path (default: discovered from the current directory)
      --key <KEY>                       Idempotency key (default: derived from the proposal; repeating resumes/replays). Not the issuer key of `ag validate run --key`; `--idempotency-key` is the unambiguous spelling [alias: --idempotency-key]
      --as <IDENTITY>                   Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --fencing-token <FENCING_TOKENS>  Fencing token(s) of exclusive leases the author holds
      --json                            Machine-readable JSON output
      --color <WHEN>                    Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet                           Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                         Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                            Print help
  -V, --version                         Print version

Exit codes: 0 integrated, 3 blocked (provide what is missing and run it again), 4 conflict, denied or invalid.
The stream is untouched unless the exit code is 0. Examples:
  ag integrate prop_8f3a1c                        any unique id prefix works
  ag integrate prop_8f3a1c --fencing-token 7      present the token of your exclusive lease
  ag --json integrate prop_8f3a1c                 stable blocker codes for scripts and agents

ag preview¶

Show what integrating a proposal would do, without doing it

Usage: ag preview [OPTIONS] <PROPOSAL>

Arguments:
  <PROPOSAL>  Proposal id

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag explain¶

Say why a proposal does not land yet, in plain words, with the exact commands that fix each reason

Usage: ag explain [OPTIONS] [PROPOSAL]

Arguments:
  [PROPOSAL]  Proposal id (any unique prefix). Default: your newest open proposal

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

Exit codes: 0 nothing is in the way, 3 blocked (something can be provided), 4 refused (conflict or denial).
Changes nothing. Examples:
  ag explain                 your newest open proposal
  ag explain prop_8f3a1c     a specific one
  ag --json explain          codes, sentences and commands for a program

ag op¶

Inspect or resume operations

Usage: ag op [OPTIONS] <COMMAND>

Commands:
  show    Show an operation's recorded state and result. Use this instead of blindly retrying when a response was lost
  resume  Resume an operation (for example one that was blocked)
  list    List recent operations

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag op show¶

Show an operation's recorded state and result. Use this instead of blindly retrying when a response was lost

Usage: ag op show [OPTIONS] <ID>

Arguments:
  <ID>  Operation id

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag op resume¶

Resume an operation (for example one that was blocked)

Usage: ag op resume [OPTIONS] <ID>

Arguments:
  <ID>  Operation id

Options:
  -C, --repo <DIR>                      Operate on the repository at this path (default: discovered from the current directory)
      --fencing-token <FENCING_TOKENS>  Fencing token(s) to present
      --as <IDENTITY>                   Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json                            Machine-readable JSON output
      --color <WHEN>                    Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet                           Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                         Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                            Print help
  -V, --version                         Print version

ag op list¶

List recent operations

Usage: ag op list [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
  -n, --limit <LIMIT>  Maximum entries [default: 20]
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag recover¶

Resume interrupted operations and expire stale ones

Usage: ag recover [OPTIONS]

Options:
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
      --max-age <MAX_AGE>  Operations untouched for longer than this are aborted [default: 7d]
      --as <IDENTITY>      Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json               Machine-readable JSON output
      --color <WHEN>       Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet              Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose            Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help               Print help
  -V, --version            Print version

ag queue¶

The ordered integration queue

Usage: ag queue [OPTIONS] <COMMAND>

Commands:
  add   Add a proposal to its stream's queue
  list  Show the queue
  run   Integrate queued proposals in order

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag queue add¶

Add a proposal to its stream's queue

Usage: ag queue add [OPTIONS] <PROPOSAL>

Arguments:
  <PROPOSAL>  Proposal id

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag queue list¶

Show the queue

Usage: ag queue list [OPTIONS] [STREAM]

Arguments:
  [STREAM]  Stream (default: the default stream); `--stream STREAM` means the same

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --stream <STREAM>  The stream, as an option (the same as the positional STREAM)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag queue run¶

Integrate queued proposals in order

Usage: ag queue run [OPTIONS] [STREAM]

Arguments:
  [STREAM]  Stream (default: the default stream); `--stream STREAM` means the same

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --stream <STREAM>  The stream, as an option (the same as the positional STREAM)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag policy¶

Show or change stream policy

Usage: ag policy [OPTIONS] <COMMAND>

Commands:
  show     Show the policy in force
  set      Replace the policy with the contents of a JSON file (needs an admin)
  history  List policy versions
  example  Print an example policy document
  preset   Ready-made policies: solo, team, agents, strict
  explain  Say in plain language what a policy allows, requires and refuses

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

Concepts and fields: ag help policy

ag policy show¶

Show the policy in force

Usage: ag policy show [OPTIONS] [STREAM]

Arguments:
  [STREAM]  Stream (default: the default stream); `--stream STREAM` means the same

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --stream <STREAM>  The stream, as an option (the same as the positional STREAM)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag policy set¶

Replace the policy with the contents of a JSON file (needs an admin)

Usage: ag policy set [OPTIONS] <FILE>

Arguments:
  <FILE>  JSON policy file

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --stream <STREAM>  Stream (default: the default stream)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag policy history¶

List policy versions

Usage: ag policy history [OPTIONS] [STREAM]

Arguments:
  [STREAM]  Stream (default: the default stream); `--stream STREAM` means the same

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --stream <STREAM>  The stream, as an option (the same as the positional STREAM)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag policy example¶

Print an example policy document

Usage: ag policy example [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag policy preset¶

Ready-made policies: solo, team, agents, strict

Usage: ag policy preset [OPTIONS] <COMMAND>

Commands:
  list   List the presets and who each is for
  show   Print the policy document a preset makes, and what it means
  apply  Store a preset as the stream's next policy version (needs an admin)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag policy preset list¶

List the presets and who each is for

Usage: ag policy preset list [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag policy preset show¶

Print the policy document a preset makes, and what it means

Usage: ag policy preset show [OPTIONS] <NAME>

Arguments:
  <NAME>  solo, team, agents or strict

Options:
      --admin <IDENTITY>       Identity pattern allowed to change the policy (repeatable). Default: you
  -C, --repo <DIR>             Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --issuer <IDENTITY=KEY>  Trust this CI issuer to sign the `tests` check: IDENTITY=PUBLIC_KEY, e.g. service:ci=<64 hex digits>
      --ci-key <NAME>          Trust the signing key NAME of this repository (created if missing; `ag validate keygen NAME` makes the same key): the issuer becomes service:NAME
      --json                   Machine-readable JSON output
      --color <WHEN>           Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet                  Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                   Print help
  -V, --version                Print version

ag policy preset apply¶

Store a preset as the stream's next policy version (needs an admin)

Usage: ag policy preset apply [OPTIONS] <NAME>

Arguments:
  <NAME>  solo, team, agents or strict

Options:
      --admin <IDENTITY>       Identity pattern allowed to change the policy (repeatable). Default: you
  -C, --repo <DIR>             Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --issuer <IDENTITY=KEY>  Trust this CI issuer to sign the `tests` check: IDENTITY=PUBLIC_KEY, e.g. service:ci=<64 hex digits>
      --ci-key <NAME>          Trust the signing key NAME of this repository (created if missing; `ag validate keygen NAME` makes the same key): the issuer becomes service:NAME
      --json                   Machine-readable JSON output
      --color <WHEN>           Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
      --stream <STREAM>        Stream (default: the default stream)
  -q, --quiet                  Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                   Print help
  -V, --version                Print version

ag policy explain¶

Say in plain language what a policy allows, requires and refuses

Usage: ag policy explain [OPTIONS] [TARGET]

Arguments:
  [TARGET]  A policy file, or `current` (the default) for the policy in force

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --stream <STREAM>  Stream whose policy `current` means (default: the default stream)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

Examples:
  ag policy explain                  the policy in force
  ag policy explain policy.json      a document, before you set it
  ag --json policy explain current   the same sentences as data

ag validate¶

Run checks and issue signed attestations

Usage: ag validate [OPTIONS] <COMMAND>

Commands:
  keygen  Generate a signing key for an issuer and print its public key
  run     Check out the exact candidate tree of a proposal, run a command on it and record a signed attestation of the result
  list    List attestations recorded for a tree

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag validate keygen¶

Generate a signing key for an issuer and print its public key

Usage: ag validate keygen [OPTIONS] <NAME>

Arguments:
  <NAME>  Key name, e.g. `ci`

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag validate run¶

Check out the exact candidate tree of a proposal, run a command on it and record a signed attestation of the result.

WARNING: the command runs on this machine without a sandbox. This runner is for trusted code and local workflows; use an isolated execution plane for untrusted code.

Usage: ag validate run [OPTIONS] --check <CHECK> --key <KEY> <PROPOSAL> -- <COMMAND>...

Arguments:
  <PROPOSAL>
          Proposal id

  <COMMAND>...
          The command and its arguments

Options:
  -C, --repo <DIR>
          Operate on the repository at this path (default: discovered from the current directory)

      --check <CHECK>
          Check name, as listed in the policy's `required_validations`

      --as <IDENTITY>
          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY

      --key <KEY>
          Name of the issuer key created with `ag validate keygen`

      --issuer <ISSUER>
          Issuer identity (default: `service:<key name>`)

      --json
          Machine-readable JSON output

      --color <WHEN>
          Colour the output: auto (a terminal, unless NO_COLOR is set), always or never

      --env <ENV>
          Environment digest to record (default: derived from the command and platform)

  -q, --quiet
          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown

  -v, --verbose
          Explain what is happening on standard error: repository, identity, remote, timing

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

ag validate list¶

List attestations recorded for a tree

Usage: ag validate list [OPTIONS] <TREE>

Arguments:
  <TREE>  Tree id (64 hex characters)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag agent¶

Agent identities and runs

Usage: ag agent [OPTIONS] <COMMAND>

Commands:
  register   Register an agent and create its signing key
  list       List agents
  start      Start a run. Prints the identity the agent must use (`agent:name#run_…`)
  finish     Finish a run and release its leases
  heartbeat  Heartbeat a running run
  runs       List runs, newest first
  reap       Abandon runs with no recent heartbeat and release their leases
  disable    Stop an agent from starting new runs
  enable     Allow a disabled agent to run again

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag agent register¶

Register an agent and create its signing key

Usage: ag agent register [OPTIONS] <NAME>

Arguments:
  <NAME>  Agent name (`[a-z0-9][a-z0-9_-]*`)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --role <ROLE>    `agent` or `reviewer` [default: agent]
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag agent list¶

List agents

Usage: ag agent list [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag agent start¶

Start a run. Prints the identity the agent must use (`agent:name#run_…`)

Usage: ag agent start [OPTIONS] <NAME>

Arguments:
  <NAME>  Agent name

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --task <TASK>    Task to work on (claims it; its dependencies must be done)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag agent finish¶

Finish a run and release its leases

Usage: ag agent finish [OPTIONS] <RUN>

Arguments:
  <RUN>  Run id

Options:
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
      --status <STATUS>    `completed` or `failed` [default: completed]
      --as <IDENTITY>      Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
  -m, --message <MESSAGE>  Summary
      --json               Machine-readable JSON output
      --color <WHEN>       Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet              Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose            Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help               Print help
  -V, --version            Print version

ag agent heartbeat¶

Heartbeat a running run

Usage: ag agent heartbeat [OPTIONS] <RUN>

Arguments:
  <RUN>  Run id

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag agent runs¶

List runs, newest first

Usage: ag agent runs [OPTIONS] [NAME]

Arguments:
  [NAME]  Only this agent

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
  -n, --limit <LIMIT>  Show at most this many (0 = all) [default: 50]
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag agent reap¶

Abandon runs with no recent heartbeat and release their leases

Usage: ag agent reap [OPTIONS]

Options:
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
      --timeout <TIMEOUT>  Heartbeat timeout (default 10m here; with `--remote`, the server's `agents.run_stale_after_secs`)
      --as <IDENTITY>      Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --dry-run            Say what would be abandoned without changing anything
      --json               Machine-readable JSON output
      --remote [<NAME>]    Reap the runs of a server instead of this repository (needs `agent.operate` there; without a NAME: origin). The server also revokes the credentials bound to the reaped runs
      --color <WHEN>       Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet              Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose            Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help               Print help
  -V, --version            Print version

ag agent disable¶

Stop an agent from starting new runs

Usage: ag agent disable [OPTIONS] <NAME>

Arguments:
  <NAME>  Agent name

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag agent enable¶

Allow a disabled agent to run again

Usage: ag agent enable [OPTIONS] <NAME>

Arguments:
  <NAME>  Agent name

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag task¶

Tasks and their dependencies

Usage: ag task [OPTIONS] <COMMAND>

Commands:
  create  Create a task
  list    List tasks
  depend  Declare that TASK cannot start until ON is done
  ready   Open tasks whose dependencies are all done
  done    Mark a task done
  cancel  Cancel a task

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag task create¶

Create a task

Usage: ag task create [OPTIONS] <TITLE>

Arguments:
  <TITLE>  Title

Options:
  -C, --repo <DIR>                 Operate on the repository at this path (default: discovered from the current directory)
  -d, --description <DESCRIPTION>  Description [default: ""]
      --as <IDENTITY>              Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --scope <SCOPE>              Path glob the task is expected to touch (repeatable)
      --json                       Machine-readable JSON output
      --color <WHEN>               Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet                      Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                    Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                       Print help
  -V, --version                    Print version

ag task list¶

List tasks

Usage: ag task list [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --state <STATE>  Filter by state: open, in_progress, done, cancelled
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag task depend¶

Declare that TASK cannot start until ON is done

Usage: ag task depend [OPTIONS] <TASK> <ON>

Arguments:
  <TASK>  The dependent task
  <ON>    The task it waits for

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag task ready¶

Open tasks whose dependencies are all done

Usage: ag task ready [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag task done¶

Mark a task done

Usage: ag task done [OPTIONS] <TASK>

Arguments:
  <TASK>  Task id

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag task cancel¶

Cancel a task

Usage: ag task cancel [OPTIONS] <TASK>

Arguments:
  <TASK>  Task id

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag lease¶

Soft and exclusive leases with fencing tokens

Usage: ag lease [OPTIONS] <COMMAND>

Commands:
  acquire  Claim a scope (path glob). Soft by default; `--exclusive` is enforced at integration
  release  Release a lease early
  extend   Extend a lease; the fencing token stays the same
  list     List active leases

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

Concepts: ag help leases

ag lease acquire¶

Claim a scope (path glob). Soft by default; `--exclusive` is enforced at integration

Usage: ag lease acquire [OPTIONS] <SCOPE>

Arguments:
  <SCOPE>  Path glob, e.g. `src/auth/**`

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --exclusive      Enforce with a fencing token at integration time
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --ttl <TTL>      How long the lease lasts [default: 1h]
      --json           Machine-readable JSON output
      --task <TASK>    Task the lease belongs to
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag lease release¶

Release a lease early

Usage: ag lease release [OPTIONS] <ID>

Arguments:
  <ID>  Lease id

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag lease extend¶

Extend a lease; the fencing token stays the same

Usage: ag lease extend [OPTIONS] <ID>

Arguments:
  <ID>  Lease id

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --ttl <TTL>      New duration from now [default: 1h]
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag lease list¶

List active leases

Usage: ag lease list [OPTIONS]

Options:
      --all            Include released and expired leases (the newest ones, see -n)
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
  -n, --limit <LIMIT>  With --all: show at most this many (0 = all) [default: 200]
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag provenance¶

Signed provenance of agent-made changes

Usage: ag provenance [OPTIONS] <COMMAND>

Commands:
  attach  Sign and attach a provenance record to a changeset
  show    Show and verify the provenance of a changeset

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag provenance attach¶

Sign and attach a provenance record to a changeset

Usage: ag provenance attach [OPTIONS] --agent <AGENT> [REV]

Arguments:
  [REV]  Changeset (default: the workspace head)

Options:
      --agent <AGENT>              Agent name (its key signs the record)
  -C, --repo <DIR>                 Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>              Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --run <RUN>                  Run id
      --json                       Machine-readable JSON output
      --task <TASK>                Task id
      --color <WHEN>               Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
      --model <MODEL>              Model identifier
      --prompt-file <PROMPT_FILE>  File holding the prompt; only its SHA-256 is stored
  -q, --quiet                      Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
      --rationale <RATIONALE>      Why the change was made
  -v, --verbose                    Explain what is happening on standard error: repository, identity, remote, timing
      --check <CHECKS>             A check the agent ran itself (repeatable)
      --input <INPUTS>             A source consulted (repeatable). Stored as untrusted text
  -h, --help                       Print help
  -V, --version                    Print version

ag provenance show¶

Show and verify the provenance of a changeset

Usage: ag provenance show [OPTIONS] [REV]

Arguments:
  [REV]  Changeset (default: the workspace head)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag predict¶

Predict overlapping work

Usage: ag predict [OPTIONS] [STREAM]

Arguments:
  [STREAM]  Stream (default: the default stream); `--stream STREAM` means the same

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --stream <STREAM>  The stream, as an option (the same as the positional STREAM)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag workspace¶

Create, list and remove workspaces (isolated lines of work in their own directories)

Usage: ag workspace [OPTIONS] <COMMAND>

Commands:
  create  Create a workspace starting at the stream head and check it out into DIR
  list    List workspaces
  remove  Forget a workspace (its directory is left alone)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag workspace create¶

Create a workspace starting at the stream head and check it out into DIR

Usage: ag workspace create [OPTIONS] --dir <DIR> <NAME>

Arguments:
  <NAME>  Workspace name

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --dir <DIR>        Directory to check out into (created if missing; must be empty)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --stream <STREAM>  Stream to track (default: the default stream)
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag workspace list¶

List workspaces

Usage: ag workspace list [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag workspace remove¶

Forget a workspace (its directory is left alone)

Usage: ag workspace remove [OPTIONS] <NAME>

Arguments:
  <NAME>  Workspace name

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag trace¶

Show the audit trail of an object, proposal, run or stream

Usage: ag trace [OPTIONS] [TARGET]

Arguments:
  [TARGET]  What to trace: a proposal id, run id, task id, stream, agent identity or changeset (prefix). Default: everything

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
  -n, --limit <LIMIT>  Maximum entries [default: 50]
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag audit¶

Verify the tamper-evident audit chain

Usage: ag audit [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --list           List recent entries instead of verifying the chain
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
  -n, --limit <LIMIT>  Number of entries for `--list` [default: 20]
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag verify¶

Check the integrity of the whole repository

Usage: ag verify [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag gc¶

Delete unreachable objects (safe: fails closed, honours a grace period)

Usage: ag gc [OPTIONS]

Options:
  -C, --repo <DIR>
          Operate on the repository at this path (default: discovered from the current directory)
      --grace <GRACE>
          Keep unreachable objects younger than this [default: 24h]
      --as <IDENTITY>
          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --reflog-retention <REFLOG_RETENTION>
          Keep heads that appeared in a reflog within this window [default: 90d]
      --dry-run
          Report only; delete nothing
      --json
          Machine-readable JSON output
      --color <WHEN>
          Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet
          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose
          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help
          Print help
  -V, --version
          Print version

ag reindex¶

Rebuild derived indexes from the object store

Usage: ag reindex [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag backup¶

Write a verified, consistent copy of the repository to a new directory

Usage: ag backup [OPTIONS] <DEST>

Arguments:
  <DEST>  Destination directory (new or empty)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --include-keys   Also copy private keys (agent and issuer identities). Off by default
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag git¶

Import from or export to Git (needs the `git` command)

Usage: ag git [OPTIONS] <COMMAND>

Commands:
  import  Import a Git repository's history into a new stream
  export  Export a stream's history to a Git repository (created if missing)

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag git import¶

Import a Git repository's history into a new stream

Usage: ag git import [OPTIONS] <PATH>

Arguments:
  <PATH>  Path of the Git repository

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --rev <REV>        Revision to import [default: HEAD]
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --stream <STREAM>  Stream to create for the imported history [default: imported]
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag git export¶

Export a stream's history to a Git repository (created if missing)

Usage: ag git export [OPTIONS] <STREAM> <PATH>

Arguments:
  <STREAM>  Stream to export
  <PATH>    Destination Git repository

Options:
      --branch <BRANCH>  Branch name in Git [default: main]
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag clone¶

Clone a repository from an `ag-server`

Usage: ag clone [OPTIONS] <URL> [DIR]

Arguments:
  <URL>  `http(s)://host:port/owner/name`
  [DIR]  Directory to create (default: the repository name)

Options:
  -C, --repo <DIR>             Operate on the repository at this path (default: discovered from the current directory)
      --stream <STREAM>        Stream to clone (default: the repository's default stream)
      --as <IDENTITY>          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --name <NAME>            Name for the remote [default: origin]
      --json                   Machine-readable JSON output
      --token-env <TOKEN_ENV>  Environment variable holding the credential (default: AG_TOKEN)
      --color <WHEN>           Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
      --token-stdin            Read the credential from stdin and store it in `.ag/credentials/<name>` (mode 0600)
      --ca-file <CA_FILE>      Extra CA certificate (PEM) to trust
  -q, --quiet                  Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                   Print help
  -V, --version                Print version

ag fetch¶

Download new history from the server

Usage: ag fetch [OPTIONS]

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote name (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --stream <STREAM>  Stream (default: the repository's default stream)
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag pull¶

Fetch, then fast-forward the local stream and bring the workspace up to date

Usage: ag pull [OPTIONS]

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote name (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --stream <STREAM>  Stream (default: the repository's default stream)
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag push¶

Upload your snapshot and open a proposal on the server

Usage: ag push [OPTIONS] --title <TITLE> [REV]

Arguments:
  [REV]  Revision to propose (default: the workspace head)

Options:
  -C, --repo <DIR>                 Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>            Remote name (default: origin)
      --as <IDENTITY>              Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
  -t, --title <TITLE>              Proposal title
  -d, --description <DESCRIPTION>  Longer description [default: ""]
      --json                       Machine-readable JSON output
      --color <WHEN>               Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
      --stream <STREAM>            Target stream (default: the repository's default stream)
  -q, --quiet                      Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
      --task <TASK>                Task this proposal belongs to
  -v, --verbose                    Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                       Print help
  -V, --version                    Print version

ag remote¶

Manage remotes and work with proposals, events and policy on a server

Usage: ag remote [OPTIONS] <COMMAND>

Commands:
  add        Add a remote
  list       List remotes
  remove     Forget a remote
  whoami     Show who the server thinks you are
  proposals  List proposals on the server
  proposal   Show a proposal with its reviews
  prepare    What would integrating do now, and what is missing?
  review     Review a proposal's current head
  integrate  Integrate a proposal into its stream
  close      Close a proposal without integrating it
  streams    List streams
  events     Show the events of the repository (replay), or follow them live
  policy     Show or set a stream's policy
  log        Show history of a revision on the server
  blame      Show which changeset introduced each line of a file on the server: `ag remote blame main:src/lib.rs`
  cat        Print a file as of a revision on the server: `ag remote cat main:src/lib.rs`

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote to use (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag remote add¶

Add a remote

Usage: ag remote add [OPTIONS] <NAME> <URL>

Arguments:
  <NAME>  Name, e.g. origin
  <URL>   `http(s)://host:port/owner/name`

Options:
  -C, --repo <DIR>             Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>        Remote to use (default: origin)
      --token-env <TOKEN_ENV>  Environment variable holding the credential
      --as <IDENTITY>          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --token-stdin            Read the credential from stdin and store it in `.ag/credentials/<name>` (mode 0600)
      --ca-file <CA_FILE>      Extra CA certificate (PEM) to trust
      --json                   Machine-readable JSON output
      --color <WHEN>           Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet                  Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                   Print help
  -V, --version                Print version

ag remote list¶

List remotes

Usage: ag remote list [OPTIONS]

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote to use (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag remote remove¶

Forget a remote

Usage: ag remote remove [OPTIONS] <NAME>

Arguments:
  <NAME>  Name

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote to use (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag remote whoami¶

Show who the server thinks you are

Usage: ag remote whoami [OPTIONS]

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote to use (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag remote proposals¶

List proposals on the server

Usage: ag remote proposals [OPTIONS]

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote to use (default: origin)
      --state <STATE>    Filter: open, integrated, closed
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag remote proposal¶

Show a proposal with its reviews

Usage: ag remote proposal [OPTIONS] <ID>

Arguments:
  <ID>  Proposal id

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote to use (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag remote prepare¶

What would integrating do now, and what is missing?

Usage: ag remote prepare [OPTIONS] <ID>

Arguments:
  <ID>  Proposal id

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote to use (default: origin)
      --validate         Also queue the validation jobs the policy knows how to run
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag remote review¶

Review a proposal's current head

Usage: ag remote review [OPTIONS] <ID>

Arguments:
  <ID>  Proposal id

Options:
      --approve            Approve
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>    Remote to use (default: origin)
      --as <IDENTITY>      Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --request-changes    Request changes
      --comment            Comment only
      --json               Machine-readable JSON output
      --color <WHEN>       Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -m, --message <MESSAGE>  Review text [default: ""]
  -q, --quiet              Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose            Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help               Print help
  -V, --version            Print version

ag remote integrate¶

Integrate a proposal into its stream

Usage: ag remote integrate [OPTIONS] <ID>

Arguments:
  <ID>  Proposal id

Options:
  -C, --repo <DIR>                      Operate on the repository at this path (default: discovered from the current directory)
      --fencing-token <FENCING_TOKENS>  Fencing tokens of exclusive leases the author holds
      --remote <REMOTE>                 Remote to use (default: origin)
      --as <IDENTITY>                   Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json                            Machine-readable JSON output
      --color <WHEN>                    Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet                           Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose                         Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                            Print help
  -V, --version                         Print version

ag remote close¶

Close a proposal without integrating it

Usage: ag remote close [OPTIONS] <ID>

Arguments:
  <ID>  Proposal id

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote to use (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag remote streams¶

List streams

Usage: ag remote streams [OPTIONS]

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote to use (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag remote events¶

Show the events of the repository (replay), or follow them live

Usage: ag remote events [OPTIONS]

Options:
      --after <AFTER>    Replay events after this sequence number [default: 0]
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote to use (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --topics <TOPICS>  Only these topics (prefix match), e.g. `stream,proposal`
      --follow           Keep following new events
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag remote policy¶

Show or set a stream's policy

Usage: ag remote policy [OPTIONS] <STREAM>

Arguments:
  <STREAM>  Stream

Options:
  -C, --repo <DIR>             Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>        Remote to use (default: origin)
      --set <SET>              Replace the policy with the JSON document in this file
      --as <IDENTITY>          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --preset <NAME>          Replace the policy with a ready-made one: solo, team, agents or strict (`ag policy preset list`)
      --explain                Also say in plain language what the policy allows, requires and refuses
      --json                   Machine-readable JSON output
      --admin <IDENTITY>       Identity pattern allowed to change the policy (repeatable). Default: you
      --color <WHEN>           Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
      --issuer <IDENTITY=KEY>  Trust this CI issuer to sign the `tests` check: IDENTITY=PUBLIC_KEY, e.g. service:ci=<64 hex digits>
  -q, --quiet                  Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
      --ci-key <NAME>          Trust the signing key NAME of this repository (created if missing; `ag validate keygen NAME` makes the same key): the issuer becomes service:NAME
  -v, --verbose                Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                   Print help
  -V, --version                Print version

ag remote log¶

Show history of a revision on the server

Usage: ag remote log [OPTIONS] [REV]

Arguments:
  [REV]  Revision (default: the default stream)

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
  -n, --limit <LIMIT>    Maximum entries [default: 20]
      --remote <REMOTE>  Remote to use (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag remote blame¶

Show which changeset introduced each line of a file on the server: `ag remote blame main:src/lib.rs`

Usage: ag remote blame [OPTIONS] <SPEC>

Arguments:
  <SPEC>  `[REV:]PATH`

Options:
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
  -L, --lines <START,END>  Only these lines, `START,END`
      --remote <REMOTE>    Remote to use (default: origin)
      --as <IDENTITY>      Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --max-commits <N>    Look at most this many changesets back (default: the server's limit; the output says when it stopped) [default: 0]
      --json               Machine-readable JSON output
      --color <WHEN>       Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet              Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose            Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help               Print help
  -V, --version            Print version

ag remote cat¶

Print a file as of a revision on the server: `ag remote cat main:src/lib.rs`

Usage: ag remote cat [OPTIONS] <SPEC>

Arguments:
  <SPEC>  `REV:PATH`

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --remote <REMOTE>  Remote to use (default: origin)
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

Save a server credential once; `clone`, `fetch`, `push` and `remote` then need no token plumbing

Usage: ag login [OPTIONS] <SERVER>

Arguments:
  <SERVER>  The server, e.g. `http://127.0.0.1:8080` (a repository URL works too; only the server part is used)

Options:
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
      --token-stdin        Read the credential from standard input (`echo "$TOKEN" | ag login URL --token-stdin`)
      --as <IDENTITY>      Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --token-file <FILE>  Read the credential from a file (`ag-server dev` writes one and prints the command)
      --ca-file <CA_FILE>  Extra CA certificate (PEM) to trust when checking the credential
      --json               Machine-readable JSON output
      --color <WHEN>       Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet              Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose            Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help               Print help
  -V, --version            Print version

The credential is stored in credentials.json beside the user configuration (`ag config path`), readable by you only.
An environment variable (AG_TOKEN) or a credential stored with a remote still takes precedence. Examples:
  ag login http://127.0.0.1:8080 --token-file ag-dev-data/dev/token
  echo "$TOKEN" | ag login https://ag.example.com --token-stdin

ag logout¶

Forget a saved server credential

Usage: ag logout [OPTIONS] [SERVER]

Arguments:
  [SERVER]  The server whose saved login to forget

Options:
      --all            Forget every saved login
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag pin¶

Pin a revision so garbage collection keeps it

Usage: ag pin [OPTIONS] <NAME> <REV>

Arguments:
  <NAME>  Pin name
  <REV>   Revision to keep

Options:
  -C, --repo <DIR>       Operate on the repository at this path (default: discovered from the current directory)
      --reason <REASON>  Why [default: ""]
      --as <IDENTITY>    Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json             Machine-readable JSON output
      --color <WHEN>     Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet            Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose          Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help             Print help
  -V, --version          Print version

ag unpin¶

Remove a pin

Usage: ag unpin [OPTIONS] <NAME>

Arguments:
  <NAME>  Pin name

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag pins¶

List pins

Usage: ag pins [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag doctor¶

Check the installation, the repository, your identity and every remote's credential

Usage: ag doctor [OPTIONS]

Options:
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
      --offline            Do not contact any server: check that credentials exist, not that they work
      --as <IDENTITY>      Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --strict             Exit with 1 when a check warns, not only when one fails
      --json               Machine-readable JSON output
      --timeout <SECONDS>  How long to wait for each server before giving up [default: 10]
      --color <WHEN>       Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet              Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose            Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help               Print help
  -V, --version            Print version

ag config¶

Show, get, set and locate configuration (the user file; the repository's settings are shown read-only)

Usage: ag config [OPTIONS] <COMMAND>

Commands:
  list   Show every setting with its effective value and where it comes from
  get    Print one setting's effective value (see `list` for the keys)
  set    Store a user-level setting: `identity` or `color`
  unset  Remove a stored user-level setting
  path   Print the locations of the configuration files

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

Files, environment variables and precedence: ag help config

ag config list¶

Show every setting with its effective value and where it comes from

Usage: ag config list [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag config get¶

Print one setting's effective value (see `list` for the keys)

Usage: ag config get [OPTIONS] <KEY>

Arguments:
  <KEY>  Setting name, for example `identity`

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag config set¶

Store a user-level setting: `identity` or `color`

Usage: ag config set [OPTIONS] <KEY> <VALUE>

Arguments:
  <KEY>    Setting name
  <VALUE>  New value

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag config unset¶

Remove a stored user-level setting

Usage: ag config unset [OPTIONS] <KEY>

Arguments:
  <KEY>  Setting name

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag config path¶

Print the locations of the configuration files

Usage: ag config path [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag completions¶

Print a shell completion script: bash, zsh, fish, powershell or elvish

Usage: ag completions [OPTIONS] <SHELL>

Arguments:
  <SHELL>  The shell to generate the script for [possible values: bash, elvish, fish, powershell, zsh]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

Examples:
  ag completions bash > ~/.local/share/bash-completion/completions/ag
  ag completions zsh  > "${fpath[1]}/_ag"
  ag completions fish > ~/.config/fish/completions/ag.fish

ag man¶

Print the man page, or write one page per command with --dir

Usage: ag man [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --dir <DIR>      Write `ag.1` and one page per subcommand (`ag-stream-list.1`, …) into this directory instead of printing the top-level page
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version

ag version¶

Print the version, the protocol and the JSON schema version

Usage: ag version [OPTIONS]

Options:
  -C, --repo <DIR>     Operate on the repository at this path (default: discovered from the current directory)
      --as <IDENTITY>  Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --json           Machine-readable JSON output
      --color <WHEN>   Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
  -q, --quiet          Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -v, --verbose        Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help           Print help
  -V, --version        Print version