ait plan — Complete Reference

ait plan
ait plan list
ait plan show
ait plan revisions
ait plan items
ait plan candidates
ait plan inspect
ait plan sync

Inspect, select, and sync Plan revision history. Without --local or --remote, solo_local uses local Plans and solo_remote uses the configured default remote. Either flag explicitly overrides that default. Remote sync updates local Plan history before publishing; no Plan command creates a Snapshot or advances a Line.

Usage: ait plan <COMMAND>

Commands:
  list        List local Plans or Plans from a remote.
  show        Show one Plan and its selected revision.
  revisions   List revision history for one Plan.
  items       List checklist items from one Plan revision.
  candidates  Find active Plans that can supply Task candidates.
  inspect     Inspect Task-readiness details for one Plan revision.
  sync        Sync file-backed Markdown into Plan revision history using the workflow mode's local or remote default. solo_local saves local Plan changes; solo_remote updates local Plan history and publishes the changed heads to the configured default remote. --local or --remote overrides that default. Plan sync never creates a Snapshot or advances a Line.
  help        Print this message or the help of the given subcommand(s)

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

List Plans locally, from --remote, or from the location selected by the workflow mode. Human output is bounded to active Plans unless --all is supplied; JSON always returns the complete command result and therefore rejects --all. This command is read-only.

Usage: ait plan list [OPTIONS]

Options:
      --local
          Use local Plans even when the workflow mode defaults to a remote

      --remote <NAME>
          Use Plans from the named remote even when the workflow mode defaults to local

      --json
          Emit the complete stable machine-readable payload

      --all
          Expand human output to include archived Plans; unavailable with --json

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

Show one Plan locally, from --remote, or from the location selected by the workflow mode. Without --revision, show the current head revision. Local selectors include PR-<ordinal>, artifact:<path>, title:<title>, and published-plan:<index>; remote selectors are the identifiers returned by remote plan list. This command is read-only.

Usage: ait plan show [OPTIONS] <PLAN>

Arguments:
  <PLAN>
          Plan selector; local canonical forms are PR-<ordinal>, artifact:<path>, title:<title>, or published-plan:<index>

Options:
      --revision <REVISION>
          Select a non-head revision; local canonical forms are plan-revision:<index>, revision-number:<number>, or published-revision:<index>

      --local
          Use local Plans even when the workflow mode defaults to a remote

      --remote <NAME>
          Use Plans from the named remote even when the workflow mode defaults to local

      --json
          Emit the complete stable machine-readable payload

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

List one Plan's revisions newest first, using local data, --remote, or the location selected by the workflow mode. Human output is bounded unless --all is supplied; JSON already returns the complete command result and therefore rejects --all. This command is read-only.

Usage: ait plan revisions [OPTIONS] <PLAN>

Arguments:
  <PLAN>
          Plan selector; local canonical forms are PR-<ordinal>, artifact:<path>, title:<title>, or published-plan:<index>

Options:
      --local
          Use local Plans even when the workflow mode defaults to a remote

      --remote <NAME>
          Use Plans from the named remote even when the workflow mode defaults to local

      --json
          Emit the complete stable machine-readable payload

      --all
          Expand human output to the complete revision history; unavailable with --json

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

List parsed checklist items from one local or remote Plan. Without --revision, inspect the current head. This command is read-only and does not change item or Task state.

Usage: ait plan items [OPTIONS] <PLAN>

Arguments:
  <PLAN>
          Plan selector; local canonical forms are PR-<ordinal>, artifact:<path>, title:<title>, or published-plan:<index>

Options:
      --revision <REVISION>
          Select a non-head revision; local canonical forms are plan-revision:<index>, revision-number:<number>, or published-revision:<index>

      --local
          Use local Plans even when the workflow mode defaults to a remote

      --remote <NAME>
          Use Plans from the named remote even when the workflow mode defaults to local

      --json
          Emit the complete stable machine-readable payload

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

Find active local or remote Plans, ordered for Task selection. By default only Plans with at least one taskable item are returned; --all also includes active Plans with zero taskable items. --contains applies case-insensitive OR matching across Plan titles, file paths and selectors, headings, and item text or refs. This command is read-only.

Usage: ait plan candidates [OPTIONS]

Options:
      --local
          Use local Plans even when the workflow mode defaults to a remote

      --remote <NAME>
          Use Plans from the named remote even when the workflow mode defaults to local

      --all
          Also include active Plans with zero taskable items; archived Plans remain excluded

      --contains <TERMS>
          Case-insensitive comma-delimited OR search across titles, paths, selectors, headings, item text, and item refs

      --json
          Emit the complete stable machine-readable payload

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

Inspect summary counts and per-item Task-readiness blockers for one local or remote Plan. Without --revision, inspect the current head. This command is read-only.

Usage: ait plan inspect [OPTIONS] <PLAN>

Arguments:
  <PLAN>
          Plan selector; local canonical forms are PR-<ordinal>, artifact:<path>, title:<title>, or published-plan:<index>

Options:
      --revision <REVISION>
          Select a non-head revision; local canonical forms are plan-revision:<index>, revision-number:<number>, or published-revision:<index>

      --local
          Use local Plans even when the workflow mode defaults to a remote

      --remote <NAME>
          Use Plans from the named remote even when the workflow mode defaults to local

      --json
          Emit the complete stable machine-readable payload

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

Sync file-backed Markdown into Plan revision history using the workflow mode's local or remote default. solo_local saves local Plan changes; solo_remote updates local Plan history and publishes the changed heads to the configured default remote. --local or --remote overrides that default. Plan sync never creates a Snapshot or advances a Line.

Usage: ait plan sync [OPTIONS] <TARGET>

Arguments:
  <TARGET>
          Repository-relative Markdown file or directory to sync into local Plan revision history

Options:
      --plan-ref <PLAN_REF>
          Select one exact [plan-ref: ...] root when one Markdown target contains multiple Plan roots

      --prune
          Archive tracked Plan artifacts missing from the complete selected target inventory

      --local
          Sync local Plan history only, even when the workflow mode defaults to a remote; never create a Snapshot or advance a Line

      --remote <NAME>
          Sync local Plan history, then publish the updated heads to the named remote even when the workflow mode defaults to local

      --rebase
          When using a remote, replay the current local Plan head after the remote rejects divergent history

      --reconcile
          Safely adopt verified divergent or mixed Plan identity before effective local reconciliation or remote publication

      --json
          Emit the complete stable machine-readable result; failed and partial-success results still exit nonzero

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