Skip to content

cli.md

Latest commit

 

History

History
3413 lines (2716 loc) · 150 KB

cli.md

File metadata and controls

3413 lines (2716 loc) · 150 KB
Raw

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

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
  migrate      Migrate every branch and tag from a full local Git clone or bundle into a new repository
  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
  auth         Inspect saved server connections without printing credentials
  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 migrate

Migrate every branch and tag from a full local Git clone or bundle into a new repository

Usage: ag migrate [OPTIONS] --namespace <NAMESPACE> <SOURCE> <DESTINATION>

Arguments:
  <SOURCE>       Full local Git clone, mirror or self-contained .bundle file
  <DESTINATION>  New destination directory. It must not exist

Options:
  -C, --repo <DIR>             Operate on the repository at this path (default: discovered from the current directory)
      --namespace <NAMESPACE>  Destination namespace, for example acme/webapp
      --as <IDENTITY>          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --dry-run                Verify the migration and report limitations without publishing a repository
      --allow-lossy            Accept reported omissions, unresolved LFS pointers and unsupported refs
      --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 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)
      --expected-head <EXPECTED_HEAD>  Refuse the update if the proposal no longer has this inspected head
      --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)
      --remote [<NAME>]  Read a server's agents instead of the local repository (without a NAME: 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 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)
      --remote [<NAME>]  Change the server's agent instead (requires agent.operate; without a NAME: 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 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)
      --remote [<NAME>]  Change the server's agent instead (requires agent.operate; without a NAME: 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 task

Tasks and their dependencies

Usage: ag task [OPTIONS] <COMMAND>

Commands:
  create    Create a task
  edit      Refine instructions before a task's first run; concurrent edits are refused
  attempts  Inspect or change a task's durable execution-attempt limit
  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
      --source-task <SOURCE_TASK>    Original task for an independent follow-up
      --color <WHEN>                 Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
      --source-run <SOURCE_RUN>      Failed or abandoned run of --source-task
      --max-attempts <MAX_ATTEMPTS>  Total runs permitted (0 leaves the server limit unset) [default: 0]
  -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 edit

Refine instructions before a task's first run; concurrent edits are refused

Usage: ag task edit [OPTIONS] <--title <TITLE>|--description <DESCRIPTION>|--scope <SCOPE>|--clear-scope> <TASK>

Arguments:
  <TASK>  Task identifier

Options:
  -C, --repo <DIR>                 Operate on the repository at this path (default: discovered from the current directory)
      --title <TITLE>              New title; omitted keeps the current title
      --as <IDENTITY>              Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --description <DESCRIPTION>  New description; an empty string clears it
      --json                       Machine-readable JSON output
      --scope <SCOPE>              Replace path scope (repeatable)
      --clear-scope                Remove the expected file-path scope (repository policy still applies)
      --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
      --remote [<NAME>]            Edit on a configured server instead of locally (default name: origin)
  -v, --verbose                    Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help                       Print help
  -V, --version                    Print version

ag task attempts

Inspect or change a task's durable execution-attempt limit

Usage: ag task attempts [OPTIONS] <TASK>

Arguments:
  <TASK>  Task identifier

Options:
  -C, --repo <DIR>           Operate on the repository at this path (default: discovered from the current directory)
      --max <MAX>            New maximum total runs; zero leaves the server limit unset
      --as <IDENTITY>        Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --expected <EXPECTED>  Limit you inspected; refuses a concurrent policy change
      --json                 Machine-readable JSON output
      --remote [<NAME>]      Use a configured server instead of the local repository
      --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?
  explain     Explain why a server proposal cannot land, with the next commands. Changes nothing
  review      Review a proposal's current head
  discussion  Read and participate in revision-bound line discussions
  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 explain

Explain why a server proposal cannot land, with the next commands. Changes nothing

Usage: ag remote explain [OPTIONS] <ID>

Arguments:
  <ID>  Proposal id (any unique prefix)

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 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 discussion

Read and participate in revision-bound line discussions

Usage: ag remote discussion [OPTIONS] <COMMAND>

Commands:
  list     List line discussions, including resolved and earlier-head threads
  replies  Read replies to a line discussion
  start    Start a thread on the exact revision and line you inspected
  reply    Reply to an open line discussion
  resolve  Resolve or reopen a thread only at the version you read

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 discussion list

List line discussions, including resolved and earlier-head threads

Usage: ag remote discussion list [OPTIONS] <ID>

Arguments:
  <ID>  Proposal id

Options:
  -C, --repo <DIR>               Operate on the repository at this path (default: discovered from the current directory)
      --page-token <PAGE_TOKEN>  Continue a preceding response [default: ""]
      --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 discussion replies

Read replies to a line discussion

Usage: ag remote discussion replies [OPTIONS] <ID> <THREAD>

Arguments:
  <ID>      Proposal id
  <THREAD>  Thread id returned by list or start

Options:
  -C, --repo <DIR>               Operate on the repository at this path (default: discovered from the current directory)
      --page-token <PAGE_TOKEN>  Continue a preceding response [default: ""]
      --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 discussion start

Start a thread on the exact revision and line you inspected

Usage: ag remote discussion start [OPTIONS] --head <HEAD> --path <PATH> --line <LINE> --message <MESSAGE> <ID>

Arguments:
  <ID>  Proposal id

Options:
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
      --head <HEAD>        Exact proposal head you inspected
      --remote <REMOTE>    Remote to use (default: origin)
      --as <IDENTITY>      Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --path <PATH>        Repository-relative file path
      --json               Machine-readable JSON output
      --line <LINE>        One-based line number
      --color <WHEN>       Colour the output: auto (a terminal, unless NO_COLOR is set), always or never
      --side <SIDE>        Side of the diff. Old-side lines require --base [default: new] [possible values: old, new]
      --base <BASE>        Exact base changeset used for the comparison [default: ""]
  -q, --quiet              Print only what was asked for: no confirmations or hints. Errors and refusals are still shown
  -m, --message <MESSAGE>  Initial discussion text
  -v, --verbose            Explain what is happening on standard error: repository, identity, remote, timing
  -h, --help               Print help
  -V, --version            Print version

ag remote discussion reply

Reply to an open line discussion

Usage: ag remote discussion reply [OPTIONS] --message <MESSAGE> <ID> <THREAD>

Arguments:
  <ID>      Proposal id
  <THREAD>  Thread id

Options:
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
  -m, --message <MESSAGE>  Reply text
      --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 discussion resolve

Resolve or reopen a thread only at the version you read

Usage: ag remote discussion resolve [OPTIONS] --expected-version <EXPECTED_VERSION> <ID> <THREAD>

Arguments:
  <ID>      Proposal id
  <THREAD>  Thread id

Options:
  -C, --repo <DIR>
          Operate on the repository at this path (default: discovered from the current directory)
      --expected-version <EXPECTED_VERSION>
          Version from the latest discussion list response
      --remote <REMOTE>
          Remote to use (default: origin)
      --as <IDENTITY>
          Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --reopen
          Reopen instead of resolving
      --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 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

ag login

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 auth

Inspect saved server connections without printing credentials

Usage: ag auth [OPTIONS] <COMMAND>

Commands:
  status  List saved connections; --check asks each server whether its saved credential still works

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 auth status

List saved connections; --check asks each server whether its saved credential still works

Usage: ag auth status [OPTIONS] [SERVER]

Arguments:
  [SERVER]  Inspect just this server (a repository URL works too)

Options:
  -C, --repo <DIR>         Operate on the repository at this path (default: discovered from the current directory)
      --check              Verify saved credentials online. Without this, status is local and works offline
      --as <IDENTITY>      Act as this identity (`user:alice`, `agent:bot#run_…`, `service:ci`). Also: AG_IDENTITY
      --timeout <TIMEOUT>  Timeout for each online check, in seconds [default: 5]
      --ca-file <CA_FILE>  Extra CA certificate (PEM) for online checks
      --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 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