Skip to content
agent-board
This text was generated by an LLM (how cgwalters uses LLMs). cgwalters has not reviewed it yet.

CLI reference

Generated from agent-board's own help by agent-board help-markdown; regenerate it with just cli-docs rather than editing it. The gh-agent-board binary is the same CLI, run as gh agent-board.

agent-board

Typed board snapshots and preview-only proposals

agent-board [OPTIONS] <COMMAND>

Commands:

  • action: Validate proposed operator mutations; never execute them
  • check: Check proposals without applying them
  • project: Inspect a project's summary and schema
  • changes: What landed, closed, opened or changed hold on the live project since a time, each line a link (read-only); --board-config's operator counts as an author whose new pull requests are listed
  • item: List or inspect board items
  • ask: Ask the operator a question as an issue, list or resolve asks
  • run: Propose run field updates, or write them with --apply
  • request: Prepare an operator-approved workflow dispatch (no network writes)
  • dispatch: Start the job an issue's newest accepted plan comment proposes, once (--dry-run prints the request)
  • epic: Check a coordinator's plan for an epic's sub-issues
  • review: Send an operator-approved review draft as the bot
  • snapshot: Save a normalized board snapshot for offline use
  • reconcile: Preview deterministic board repairs; never apply them
  • poll: One pass of the pull request poll, previewed or applied; says when the next is due
  • pass: One scheduled pass: follow up pull requests, apply and plan live epics, then choose and start board work by Priority, WIP and pace; previews unless --apply (docs/pass.md)
  • budget: What each item under the board's open epics has cost, sub-issues included, beside the board's weekly budget and each item's Budget ($) field, or with --split a window's spend split between upstream work and the harness (read-only; docs/pass.md#budget-tree)
  • prune: Open issues of the board's work repositories that are candidates to close (overtaken, duplicate, stale or triaged done), each with its reasons and evidence, unless labelled keep (read-only; docs/prune.md)
  • supervise: The controller's supervisor: a read-only health pass, whether its agent runs, and the executor of its dispatch requests
  • status: How loaded the --owner organization is: runner jobs, agent runs, pools, merge queues and, with --project, the board (read-only; GH_TOKEN reads)
  • release-train: One pass of the release train: cut a release and move its callers' pins, a step a pass (prints unless --apply)
  • broker: Probe the inference broker and keep one outage issue open while it is unreachable
  • apps: Create the per-role GitHub Apps (docs/apps.md)
  • test: Run the credential-bearing staging integration test

Global options:

  • --policy <POLICY>: Trusted identity policy; defaults to the policy compiled from this repository
  • --snapshot <SNAPSHOT>: Read an offline board snapshot instead of GitHub
  • --json <FIELDS>: Print selected comma-separated JSON fields
  • --jq <JQ>: Filter JSON output with a jq expression
  • -R, --repo <REPO>: Repository OWNER/REPO for filtering or bare item numbers
  • --hostname <HOSTNAME>: GitHub hostname (only github.com is supported for live reads) (default: github.com)
  • --owner <OWNER>: Organization or user owning the live project
  • --project <PROJECT>: Live project number, not its node ID
  • --board-config <FILE>: Trusted default-branch agent-board.json whose board names the forge (GitHub by default)

agent-board action

Validate proposed operator mutations; never execute them

agent-board action [OPTIONS] <COMMAND>

Commands:

  • check: Print the newest accepted proposal's typed mutations without writing

agent-board action check

Print the newest accepted proposal's typed mutations without writing

agent-board action check [OPTIONS] --config <FILE> <ISSUE>

Arguments:

  • <ISSUE>: Issue holding the proposal: URL, OWNER/REPO#N, or N with --repo

Options:

  • --config <FILE>: Repository-owned configuration from a protected default-branch checkout

agent-board check

Check proposals without applying them

agent-board check [OPTIONS] <COMMAND>

Commands:

  • proposals: Refuse outputs outside an identity's assignment and field policy

agent-board check proposals

Refuse outputs outside an identity's assignment and field policy

agent-board check proposals [OPTIONS] --as <IDENTITY>

Options:

  • --as <IDENTITY>: Identity from the policy whose bounds the proposals must stay within
  • --proposals <FILE>: JSONL proposals file; reads stdin when omitted

agent-board project

Inspect a project's summary and schema

agent-board project [OPTIONS] <COMMAND>

Commands:

  • view: Show item counts and available fields (use --json for snapshot data)
  • init: Create the Turn, Run and Result fields dispatch needs, if missing (writes)
  • status-update: Publish a project status update (writes; requires project write permission)

agent-board project view

Show item counts and available fields (use --json for snapshot data)

agent-board project view [OPTIONS]

agent-board project init

Create the Turn, Run and Result fields dispatch needs, if missing (writes)

agent-board project init [OPTIONS]

agent-board project status-update

Publish a project status update (writes; requires project write permission)

agent-board project status-update [OPTIONS] --status <STATUS>

Options:

  • --status <STATUS>: Overall project health (possible values: on-track, at-risk, off-track)
  • --body <FILE>: Read the update body from a UTF-8 file; otherwise post the changes since the last update

agent-board changes

What landed, closed, opened or changed hold on the live project since a time, each line a link (read-only); --board-config's operator counts as an author whose new pull requests are listed

agent-board changes [OPTIONS] --since <SINCE>

Options:

  • --since <SINCE>: Start of the window, RFC 3339 (such as 2026-10-23T00:00:00Z)
  • --until <UNTIL>: End of the window, RFC 3339; without it, the window runs to now
  • --format <FORMAT>: Output format (possible values: markdown, json) (default: markdown)
  • --public-only: Leave out issues and pull requests of private repositories, for a list that will be published
  • --max-chars <N>: Trim the Markdown to at most N characters as a generated status update is trimmed: the longest sections lose their last lines first, each ending with +K more

agent-board item

List or inspect board items

agent-board item [OPTIONS] <COMMAND>

Commands:

  • list: List board items, including closed issues by default
  • view: Inspect an item by URL, OWNER/REPO#N, or N with --repo
  • search: Find open board issues of --config's workRepositories by title or body text (read-only)
  • add: Add an issue to the board, optionally setting Priority (writes with --apply)
  • edit: Set single-select or text fields on a board issue (writes with --apply)

agent-board item list

List board items, including closed issues by default

agent-board item list [OPTIONS]

Options:

  • --status <STATUS>: Filter by exact board status (for example "In Progress")
  • --priority <PRIORITY>: Filter by priority: P0 to P3
  • --turn <TURN>: Filter by whose turn it is (for example Coordinator)
  • --state <STATE>: Filter by issue state (possible values: open, closed, all) (default: all)
  • -L, --limit <LIMIT>: Maximum number of items to display (default: 30)
  • --off-board: List the open issues of --config's workRepositories that are not on its board instead, without filters
  • --config <FILE>: The pass configuration (docs/pass.md), from a trusted default-branch checkout: the open issues of its workRepositories are read beside its board's. GH_TOKEN reads; nothing is written
  • --cache <FILE>: The response cache: read if it exists, so unchanged pages are revalidated and cost no rate budget, then replaced by the responses this read used

agent-board item view

Inspect an item by URL, OWNER/REPO#N, or N with --repo

agent-board item view [OPTIONS] <ITEM>

Arguments:

  • <ITEM>: Item URL, OWNER/REPO#N, or N with --repo

Find open board issues of --config's workRepositories by title or body text (read-only)

agent-board item search [OPTIONS] <TEXT>

Arguments:

  • <TEXT>: Text to find in a title or body, ignoring case

Options:

  • --config <FILE>: The pass configuration (docs/pass.md), from a trusted default-branch checkout: the open issues of its workRepositories are read beside its board's. GH_TOKEN reads; nothing is written
  • --cache <FILE>: The response cache: read if it exists, so unchanged pages are revalidated and cost no rate budget, then replaced by the responses this read used
  • -L, --limit <LIMIT>: Maximum number of items to display (default: 30)

agent-board item add

Add an issue to the board, optionally setting Priority (writes with --apply)

agent-board item add [OPTIONS] <ITEM>

Arguments:

  • <ITEM>: Issue URL, OWNER/REPO#N, or N with --repo

Options:

  • --priority <PRIORITY>: Priority option to set, for example P1
  • --turn <TURN>: Turn option; defaults to Coordinator when the board offers it
  • --apply: Write to the live board with your token; without it, only print the proposal

agent-board item edit

Set single-select or text fields on a board issue (writes with --apply)

agent-board item edit [OPTIONS] --field <NAME=VALUE> <ITEM>

Arguments:

  • <ITEM>: Issue URL, OWNER/REPO#N, or N with --repo

Options:

  • --field <NAME=VALUE>: Set a single-select or text field, for example Status=Todo (repeatable)
  • --apply: Write to the live board with your token; without it, only print the proposal

agent-board ask

Ask the operator a question as an issue, list or resolve asks

agent-board ask [OPTIONS] <COMMAND>

Commands:

  • add: Append to the configured decisions document (preview unless --apply)
  • read: Report edits since the bot's last write to the decisions document
  • create: Open a question issue and label it and the blocked item needs-human (writes with --apply)
  • list: List open board issues labelled question
  • resolve: Comment the answer, close the ask and unlabel the item it blocked (writes with --apply)

agent-board ask add

Append to the configured decisions document (preview unless --apply)

agent-board ask add [OPTIONS] --context <CONTEXT> --option <OPTIONS> --recommend <RECOMMEND> --item <ITEM> --priority <PRIORITY> <QUESTION>

Arguments:

  • <QUESTION>: Question shown in the decision heading

Options:

  • --config <FILE>: Caller-owned agent-board.json from a trusted default-branch checkout (default: agent-board.json)
  • --context <CONTEXT>: Background paragraph, without headings or fences
  • --option <OPTIONS>: Alternative answer (repeat 2 to 10 times)
  • --recommend <RECOMMEND>: Reason to recommend the first option (A)
  • --item <ITEM>: Blocked issue, OWNER/REPO#N
  • --priority <PRIORITY>: Priority of the blocked decision (possible values: P0, P1, P2)
  • --apply: Update the issue with your token; otherwise only print the merged body

agent-board ask read

Report edits since the bot's last write to the decisions document

agent-board ask read [OPTIONS]

Options:

  • --config <FILE>: Caller-owned agent-board.json from a trusted default-branch checkout (default: agent-board.json)

agent-board ask create

Open a question issue and label it and the blocked item needs-human (writes with --apply)

agent-board ask create [OPTIONS] --item <ITEM> --assignee <ASSIGNEE> <QUESTION>

Arguments:

  • <QUESTION>: The question to ask

Options:

  • --item <ITEM>: The board issue the question blocks: URL, OWNER/REPO#N, or N with --repo
  • --assignee <ASSIGNEE>: The operator's GitHub login; the ask is assigned to them
  • --option <TEXT>: An alternative to choose from, lettered A, B, ... in order (repeat 2 to 10 times)
  • --recommend <WHY>: Recommend the first option (A), for this reason
  • --context <CONTEXT>: Background printed before the question
  • --title <TITLE>: Issue title; defaults to the question on one line, cut to 100 characters
  • --apply: Open the issue, add it to the board and label the item with your token; without it, only print proposals

agent-board ask list

List open board issues labelled question

agent-board ask list [OPTIONS]

Options:

  • -L, --limit <LIMIT>: Maximum number of asks to display (default: 30)

agent-board ask resolve

Comment the answer, close the ask and unlabel the item it blocked (writes with --apply)

agent-board ask resolve [OPTIONS] <ITEM> <ANSWER>

Arguments:

  • <ITEM>: The ask: URL, OWNER/REPO#N, or N with --repo
  • <ANSWER>: The answer, posted as a comment before the ask is closed

Options:

  • --config <FILE>: Caller-owned agent-board.json from a trusted default-branch checkout (default: agent-board.json)
  • --apply: Comment, close and unlabel with your token; without it, only print proposals

agent-board run

Propose run field updates, or write them with --apply

agent-board run [OPTIONS] <COMMAND>

Commands:

  • record: Propose recording an operator-verified run and optional applied result

agent-board run record

Propose recording an operator-verified run and optional applied result

agent-board run record [OPTIONS] --item <ITEM>

Options:

  • --item <ITEM>: Dispatched issue: URL, OWNER/REPO#N, or N with --repo
  • --run <RUN>: Actions URL selected and verified by the operator, not agent prose
  • --result <RESULT>: Applied pull request or issue comment URL. Omit for admission only
  • --apply: Write the validated proposal to the live board with your GH_TOKEN
  • --caller <CALLER>: Dispatch caller repository to search when no Run is recorded
  • --kind <KIND>: Dispatch kind to match when looking up a run (possible values: implement, triage, research) (default: implement)
  • --yes: Accept the unique run printed by caller lookup

agent-board request

Prepare an operator-approved workflow dispatch (no network writes)

agent-board request [OPTIONS] <COMMAND>

Commands:

  • dispatch: Print gh argv for one eligible issue; does not execute it

agent-board request dispatch

Print gh argv for one eligible issue; does not execute it

agent-board request dispatch [OPTIONS] --item <ITEM> --caller <CALLER>

Options:

  • --item <ITEM>: Issue to dispatch: URL, OWNER/REPO#N, or N with --repo
  • --caller <CALLER>: Repository containing the reviewed dispatch.yml caller, not the target code
  • --branch <BRANCH>: Caller default branch; the caller independently checks this (default: main)
  • --kind <KIND>: Profile the caller workflow runs with (possible values: implement, triage, research) (default: implement)

agent-board dispatch

Start the job an issue's newest accepted plan comment proposes, once (--dry-run prints the request)

agent-board dispatch [OPTIONS] --caller <OWNER/REPO> --workflow <FILE> --operator <LOGIN> <ISSUE>

Arguments:

  • <ISSUE>: Issue whose newest accepted plan comment to dispatch: URL, OWNER/REPO#N, or N with --repo

Options:

  • --dry-run: Print the workflow_dispatch request instead of sending it
  • --apply: Send it, unless this plan has been dispatched already, and record the run in one comment on the issue, with GH_TOKEN; the run is started with DISPATCH_TOKEN if set
  • --caller <OWNER/REPO>: Repository whose --workflow the request starts; from the caller's configuration
  • --workflow <FILE>: Workflow file in --caller that takes a plan's inputs, such as dispatch.yml
  • --ref <GIT_REF>: Ref of the caller to run --workflow from (default: main)
  • --operator <LOGIN>: Login whose plans count: the operator
  • --planner <LOGIN>: Login the planning run comments as, whose plans also count
  • --batch <N>: Add up to N small, ready sub-issues of the issue's epic, each with its own implement plan, to one run; 0 runs the issue alone. From the caller's configuration (default: 0)
  • --bot <LOGIN>: Login that opens the implement runs' pull requests: before dispatching, compare the issue with its open pull requests and the runs in flight on the plan's repository, and wait for or run beside them. Off without it; from the caller's configuration
  • --collaborators-only: Refuse the plan unless each issue the run reads is locked and was written only by accounts with write access to its repository. Off without it; from the caller's configuration
  • --status-app-id <ID>: With --collaborators-only, also admit issue comments that the GitHub App with this id posted as its bot: the status app (docs/apps.md). From the caller's configuration

agent-board epic

Check a coordinator's plan for an epic's sub-issues

agent-board epic [OPTIONS] <COMMAND>

Commands:

  • plan: Print the mutations the newest accepted epic plan on an epic would make (--dry-run only)
  • apply: Apply the newest accepted epic plan once (dry run is the default; --apply writes)

agent-board epic plan

Print the mutations the newest accepted epic plan on an epic would make (--dry-run only)

agent-board epic plan [OPTIONS] --dry-run --operator <LOGIN> <ISSUE>

Arguments:

  • <ISSUE>: Epic whose newest accepted epic plan to check: URL, OWNER/REPO#N, or N with --repo

Options:

  • --dry-run: Print the mutations instead of making them (required; use epic apply --apply to make them)
  • --operator <LOGIN>: Login whose plans count: the operator
  • --planner <LOGIN>: Login the planning run comments as, whose plans also count
  • --allow-repo <OWNER/REPO>: Repository whose issues a plan may create or change; repeat for each. From the caller's configuration
  • --priority-option <OPTION>: An option of the board's Priority field; repeat for each

agent-board epic apply

Apply the newest accepted epic plan once (dry run is the default; --apply writes)

agent-board epic apply [OPTIONS] --config <FILE> <ISSUE>

Arguments:

  • <ISSUE>: Epic URL, OWNER/REPO#N, or N with --repo

Options:

  • --config <FILE>: Trusted configuration file from a protected default-branch checkout
  • --apply: Write with the configured bot's token
  • --expect-request <ID>: Refuse unless the newest trusted plan has this request identifier
  • --expect-comment <ID>: Refuse unless the newest trusted plan is this comment
  • --expect-updated-at <RFC3339>: Refuse unless the plan's last edit (or creation) is this RFC 3339 instant

agent-board review

Send an operator-approved review draft as the bot

agent-board review [OPTIONS] <COMMAND>

Commands:

  • send: Post the newest review draft on an issue once the operator approves it (dry run unless --apply)

agent-board review send

Post the newest review draft on an issue once the operator approves it (dry run unless --apply)

agent-board review send [OPTIONS] --config <FILE> <ISSUE>

Arguments:

  • <ISSUE>: Draft issue URL, OWNER/REPO#N, or N with --repo

Options:

  • --config <FILE>: Trusted agent-board.json from a protected default-branch checkout: operator, bot and review
  • --dry-run: Print the requests without writing (the default)
  • --apply: Send with the configured bot's token
  • --approved-by-edit <EVENT>: The operator's approval is their ticking the body's checkbox, not a /send comment: the issues: edited event payload of that edit, such as $GITHUB_EVENT_PATH, which binds the send to the body it left

agent-board snapshot

Save a normalized board snapshot for offline use

agent-board snapshot [OPTIONS] <COMMAND>

Commands:

  • create: Write the complete normalized snapshot as JSON to stdout

agent-board snapshot create

Write the complete normalized snapshot as JSON to stdout

agent-board snapshot create [OPTIONS]

agent-board reconcile

Preview deterministic board repairs; never apply them

agent-board reconcile [OPTIONS] <COMMAND>

Commands:

  • plan: Propose repairs from a live board or offline snapshot

agent-board reconcile plan

Propose repairs from a live board or offline snapshot

agent-board reconcile plan [OPTIONS]

Options:

  • --emit: Write safe-output proposals as JSONL, not authorized mutations
  • --config <FILE>: Trusted default-branch agent-board.json; statusReconcile is off by default

agent-board poll

One pass of the pull request poll, previewed or applied; says when the next is due

agent-board poll [OPTIONS]

Options:

  • --config <FILE>: Repository-owned agent-board.json from a trusted default-branch checkout, never a dispatched pull request or workflow input. File settings win
  • --pools <FILE>: Repository-owned pools file (each pool's tier), from the same trusted checkout, needed only where fixPools or kindPools names a tier such as tier-1
  • --fix-bounds <FILE>: The caller's agentic-job bounds file for its fix kind (such as .github/agentic-job/fix.toml), from the same trusted checkout, never a dispatched head or workflow input: a pull request whose repository is outside its repos, or whose head branch is outside its push_to_pull_request_branch branches, gets no fix, rebase, continuation or answer round and is left to the operator, nor does a fix round on the operator's comments start there. The policy step stays the boundary
  • --dry-run: Print the step a pass would take for each pull request and take none
  • --apply: Take the steps: start fix and continuation runs, merge an approved green head, and label needs-human, with GH_TOKEN (the bot's); fix runs are started with DISPATCH_TOKEN if set. Only in --follow repositories, and on the operator's comments where the config's operatorComments names
  • --state <FILE>: Poll state file (cached responses, the events pages last read, the idle interval); created if missing. Keep it where only the poll writes it: its bodies are trusted
  • --follow <OWNER/REPO>: Repository whose open pull requests by --bot get a step; its activity is read too. Repeatable
  • --watch <OWNER/REPO>: Repository whose activity is read, besides those on the board given by --owner/--project or --snapshot. Repeatable
  • --operator <LOGIN>: Login whose activity is direction and whose review of a head counts
  • --bot <LOGIN>: Login whose pull requests are followed and whose activity is state
  • --dispatch-repo <OWNER/REPO>: Repository whose dispatch runs the fix markers name
  • --dispatch-workflow <FILE>: Workflow file in --dispatch-repo that --apply starts fix runs with
  • --review-workflow <FILE>: Workflow file of the review job in each --follow repository. Its reviews of a head count as the verdict only with this, and only from a run of it on pull_request_target for that head of a --bot dispatch pull request from its fork into a public repository; without it only --operator's count
  • --fix-pool <POOL>: The workflow's pool input for each fix round in turn. Repeatable; none leaves its default

agent-board pass

One scheduled pass: follow up pull requests, apply and plan live epics, then choose and start board work by Priority, WIP and pace; previews unless --apply (docs/pass.md)

agent-board pass [OPTIONS] --config <FILE>

Options:

  • --config <FILE>: The pass configuration (docs/pass.md), from a trusted default-branch checkout. Credentials come from GH_TOKEN (the bot's) and DISPATCH_TOKEN, never the file
  • --fix-bounds <FILE>: The caller's agentic-job bounds file for its fix kind (such as .github/agentic-job/fix.toml), from the same trusted checkout, never a dispatched head or workflow input: a pull request whose repository is outside its repos, or whose head branch is outside its push_to_pull_request_branch branches, gets no fix, rebase or continuation round and is left to the operator. The policy step stays the boundary
  • --apply: Take the steps: follow up pull requests, publish the usage snapshot, apply epic plans, start the chosen runs, write board Status and, with holds, publish the hold snapshot as GH_TOKEN's bot, starting runs with DISPATCH_TOKEN if set. Without it the pass previews and writes nothing. In a GitHub Actions run (GITHUB_REPOSITORY, GITHUB_RUN_ID), work starts only while no other run of its workflow is in progress. Outside one, it needs both --max-dispatch and --max-writes, and is not serialized against the scheduled workflow
  • --max-dispatch <N>: Start at most N agent runs in this pass: pull request fix, rebase and continuation rounds, an epic's planning run, and scheduled starts. The rest are held, each line saying so
  • --max-writes <N>: Take at most N other write steps in this pass: forge writes such as comments, labels, merges, the usage and hold snapshots, epic plans and Status (a pull request's comment, label, retitle, retarget, enqueue or merge step, the usage and hold comments' edits, an epic plan's receipt and each of its actions that writes, and each item's Status change). A step is taken whole or held whole, and an epic plan's steps together
  • --max-status-changes <N>: Refuse the board Status stage whole when it would change more than N items' Status [default: 50]: the first pass over a board that drifted is looked at first. Pass a higher N once to let it through
  • --replay <FILE>: Preview a recorded pass (a replay fixture) at its clock instead of reading GitHub; needs no token. With --record, it seeds the recording instead: its answers stand in for live reads, such as a usage snapshot the token cannot read or the broker's /usage
  • --record <FILE>: Preview live, and save every read and its answer to FILE as a replay fixture

agent-board budget

What each item under the board's open epics has cost, sub-issues included, beside the board's weekly budget and each item's Budget ($) field, or with --split a window's spend split between upstream work and the harness (read-only; docs/pass.md#budget-tree)

agent-board budget [OPTIONS] --config <FILE>

Options:

  • --config <FILE>: The pass configuration (docs/pass.md), from a trusted default-branch checkout: its epics.repository, board, bot, budget.weeklyUsd and, for --split, budget.harnessRepositories. GH_TOKEN reads
  • --split: Instead of the tree, print the share of the window's public spend on upstream work and on the harness (budget.harnessRepositories), in percentages only
  • --since <TIME>: Start of the --split window, RFC 3339 (such as 2026-10-19T00:00:00Z)
  • --until <TIME>: End of the --split window, RFC 3339; without it, the window runs to now

agent-board prune

Open issues of the board's work repositories that are candidates to close (overtaken, duplicate, stale or triaged done), each with its reasons and evidence, unless labelled keep (read-only; docs/prune.md)

agent-board prune [OPTIONS] --config <FILE>

Options:

  • --config <FILE>: The pass configuration (docs/pass.md), from a trusted default-branch checkout: its workRepositories are read, board gives each issue's Priority and bot names the bot whose activity does not count. GH_TOKEN reads; nothing is written to the forge
  • --stale-days <DAYS>: Days without activity by a person or a pull request after which an issue at neither P0 nor P1 is stale (1 to 365) (default: 21)
  • --cache <FILE>: The response cache: read if it exists, so unchanged pages are revalidated and cost no rate budget, then replaced by the responses this read used
  • --format <FORMAT>: Output format (possible values: text, json) (default: text)

agent-board supervise

The controller's supervisor: a read-only health pass, whether its agent runs, and the executor of its dispatch requests

agent-board supervise [OPTIONS] <COMMAND>

Commands:

  • health: Read the health observations and write the report (read-only; GH_TOKEN reads)
  • trigger: Say whether the agent runs on this pass and print its inputs for $GITHUB_OUTPUT
  • execute: Perform the agent's validated dispatch requests and log them (writes with GH_TOKEN, the bot's)
  • due: Say whether this pass is a sweep, from the previous run's times, for $GITHUB_OUTPUT (offline)
  • repeat: Say whether to skip the trigger because no check newly fails, for $GITHUB_OUTPUT (offline)
  • compose: Compose the agent's task from the pinned profile, the trigger's task and the operator request (GH_TOKEN reads)
  • preview: Print the agent's result comment without applying it (GH_TOKEN reads)
  • session: Print an operator session's wrapper inputs for $GITHUB_OUTPUT (GH_TOKEN reads)

agent-board supervise health

Read the health observations and write the report (read-only; GH_TOKEN reads)

agent-board supervise health [OPTIONS] --config <FILE> --supervisor-config <FILE>

Options:

  • --config <FILE>: The poll's agent-board.json: operator, bot, dispatch repository and workflow, follow
  • --supervisor-config <FILE>: The supervisor's settings: workflows, thresholds, the release and wrapper to compare, the agent
  • --usage-config <FILE>: Where the usage snapshot is ({repo, issue, bot}); without it the pace check is unavailable
  • --previous <FILE>: The previous pass's report, for how long an observation has been unavailable
  • --out <FILE>: Where the report is written (default: health.json)

agent-board supervise trigger

Say whether the agent runs on this pass and print its inputs for $GITHUB_OUTPUT

agent-board supervise trigger [OPTIONS] --config <FILE> --supervisor-config <FILE> --pools <FILE>

Options:

  • --config <FILE>: The poll's agent-board.json: operator, bot, dispatch repository and workflow, follow
  • --supervisor-config <FILE>: The supervisor's settings: workflows, thresholds, the release and wrapper to compare, the agent
  • --usage-config <FILE>: Where the usage snapshot is ({repo, issue, bot}); without it the pace check is unavailable
  • --pools <FILE>: The pools file naming each pool's agent, model and budget
  • --health <FILE>: The report health wrote (default: health.json)
  • --daily: The daily pass, which runs the agent with every check passing

agent-board supervise execute

Perform the agent's validated dispatch requests and log them (writes with GH_TOKEN, the bot's)

agent-board supervise execute [OPTIONS] --config <FILE> --supervisor-config <FILE> --pools <FILE> --result-url <URL>

Options:

  • --config <FILE>: The poll's agent-board.json: operator, bot, dispatch repository and workflow, follow
  • --supervisor-config <FILE>: The supervisor's settings: workflows, thresholds, the release and wrapper to compare, the agent
  • --usage-config <FILE>: Where the usage snapshot is ({repo, issue, bot}); without it the pace check is unavailable
  • --pools <FILE>: The pools file; a request must name one of its pools
  • --result-url <URL>: The agent run's result URL: its comment on the requests issue

agent-board supervise due

Say whether this pass is a sweep, from the previous run's times, for $GITHUB_OUTPUT (offline)

agent-board supervise due [OPTIONS] --event <EVENT>

Options:

  • --event <EVENT>: The event that started the run (github.event_name)
  • --prompt <PROMPT>: The dispatch's prompt; one makes a prompt-less dispatch an explicit request
  • --previous <FILE>: The previous run's times. Give it whenever the lookup worked, even if there was no previous run; left out, the times are unknown and only an explicit request is a sweep
  • --out <FILE>: Where this run's times are written, for the next run to read (default: times.json)

agent-board supervise repeat

Say whether to skip the trigger because no check newly fails, for $GITHUB_OUTPUT (offline)

agent-board supervise repeat [OPTIONS] --config <FILE> --supervisor-config <FILE>

Options:

  • --config <FILE>: The poll's agent-board.json: operator, bot, dispatch repository and workflow, follow
  • --supervisor-config <FILE>: The supervisor's settings: workflows, thresholds, the release and wrapper to compare, the agent
  • --usage-config <FILE>: Where the usage snapshot is ({repo, issue, bot}); without it the pace check is unavailable
  • --health <FILE>: The report health wrote (default: health.json)
  • --previous <FILE>: The previous run's report
  • --daily: A sweep, which never skips

agent-board supervise compose

Compose the agent's task from the pinned profile, the trigger's task and the operator request (GH_TOKEN reads)

agent-board supervise compose [OPTIONS] --config <FILE> --supervisor-config <FILE> --task <TASK> --event <FILE>

Options:

  • --config <FILE>: The poll's agent-board.json: operator, bot, dispatch repository and workflow, follow
  • --supervisor-config <FILE>: The supervisor's settings: workflows, thresholds, the release and wrapper to compare, the agent
  • --usage-config <FILE>: Where the usage snapshot is ({repo, issue, bot}); without it the pace check is unavailable
  • --task <TASK>: The task trigger printed
  • --prompt <PROMPT>: The dispatch's prompt; an operator comment's body takes its place
  • --event <FILE>: The event payload ($GITHUB_EVENT_PATH)

agent-board supervise preview

Print the agent's result comment without applying it (GH_TOKEN reads)

agent-board supervise preview [OPTIONS] --config <FILE> --supervisor-config <FILE> --result-url <URL>

Options:

  • --config <FILE>: The poll's agent-board.json: operator, bot, dispatch repository and workflow, follow
  • --supervisor-config <FILE>: The supervisor's settings: workflows, thresholds, the release and wrapper to compare, the agent
  • --usage-config <FILE>: Where the usage snapshot is ({repo, issue, bot}); without it the pace check is unavailable
  • --result-url <URL>: The agent run's result URL: its comment on the requests issue

agent-board supervise session

Print an operator session's wrapper inputs for $GITHUB_OUTPUT (GH_TOKEN reads)

agent-board supervise session [OPTIONS] --config <FILE> --supervisor-config <FILE> --session <FILE> --rules <FILE> --pools <FILE> --pool <POOL>

Options:

  • --config <FILE>: The poll's agent-board.json: operator, bot, dispatch repository and workflow, follow
  • --supervisor-config <FILE>: The supervisor's settings: workflows, thresholds, the release and wrapper to compare, the agent
  • --usage-config <FILE>: Where the usage snapshot is ({repo, issue, bot}); without it the pace check is unavailable
  • --session <FILE>: The session settings: enabled, repository, issue, idleMinutes
  • --rules <FILE>: The session's own rules, put before the supervisor's profile
  • --pools <FILE>: The pools file
  • --pool <POOL>: The pool, of the pools file, the session runs on
  • --idle-minutes <IDLE_MINUTES>: The idle timeout, 1 to 60 minutes; empty uses the session settings'
  • --prompt <PROMPT>: The opening prompt, task data

agent-board status

How loaded the --owner organization is: runner jobs, agent runs, pools, merge queues and, with --project, the board (read-only; GH_TOKEN reads)

agent-board status [OPTIONS] --config <FILE>

Options:

  • --config <FILE>: Repository-owned agent-board.json from a trusted default-branch checkout: the dispatch repository and workflow whose runs are agent runs, the followed repositories whose queues are shown, and pace, where the usage snapshot is
  • --job-limit <N>: Concurrent hosted-job limit to compare running jobs against

agent-board release-train

One pass of the release train: cut a release and move its callers' pins, a step a pass (prints unless --apply)

agent-board release-train [OPTIONS] --config <FILE>

Options:

  • --config <FILE>: The train's configuration from a trusted default-branch checkout: the bot, the release repository, the wrappers and callers to pin, labels and thresholds
  • --apply: Take the pass's step with GH_TOKEN, the bot's; without it the pass only reads and prints

agent-board broker

Probe the inference broker and keep one outage issue open while it is unreachable

agent-board broker [OPTIONS] <COMMAND>

Commands:

  • probe: Probe the broker (TCP, then one HTTP request) and open, refresh or close the outage issue; prints unless --apply, and fails while the broker is unreachable

agent-board broker probe

Probe the broker (TCP, then one HTTP request) and open, refresh or close the outage issue; prints unless --apply, and fails while the broker is unreachable

agent-board broker probe [OPTIONS] --config <FILE>

Options:

  • --config <FILE>: The probe's configuration from a trusted default-branch checkout: the broker's url, and the outage issue's repository and label
  • --apply: Open, refresh or close the outage issue with GH_TOKEN, the bot's; without it the probe reads and prints each write

agent-board apps

Create the per-role GitHub Apps (docs/apps.md)

agent-board apps [OPTIONS] <COMMAND>

Commands:

  • create: Register a role's GitHub App from the roles config through GitHub's manifest flow (one browser click)

agent-board apps create

Register a role's GitHub App from the roles config through GitHub's manifest flow (one browser click)

agent-board apps create [OPTIONS] --org <ORG> --role <ROLE>

Options:

  • --org <ORG>: The organization that will own the app
  • --role <ROLE>: The role in the roles config whose app this is
  • --config <FILE>: The roles config (JSON); defaults to the roles compiled from this repository
  • --key-file <FILE>: Write the new app's private key to FILE (created with mode 0600; an existing file is refused)
  • --key-stdout: Print the new app's private key on stdout, and everything else on stderr
  • --key-stored: The role's app exists and its private key is already stored: reuse it instead of creating one

agent-board test

Run the credential-bearing staging integration test

agent-board test [OPTIONS] <COMMAND>

Commands:

  • project: Create and clean up scratch objects in the staging project (writes)

agent-board test project

Create and clean up scratch objects in the staging project (writes)

agent-board test project [OPTIONS]

Options:

  • --create-project: Create and delete a throwaway project instead of using --project
  • --sweep: Sweeping remains disabled: names and descriptions cannot authorize deletion