Toast CLI

Minimal CLI for Toast Review CI workflows.

Review CI helps AI agents get reviewed pull requests across the finish line. Agents can edit code, run tests, push fixes, reply to comments, and resolve threads. They cannot easily maintain durable PR state across GitHub webhooks, review requests, review threads, check runs, mergeability, and follow-up reviewer activity after each push.

Toast already receives those events. The CLI gives agents one compact contract: next returns what is blocking, wait waits on Toast's webhook-fed PR state, and ready means the current PR head has cleared the configured review/check/mergeability gate. Agents do not need to fetch the head SHA first; Toast binds omitted-head waits to the reconciled current PR head so stale ready results are not reported if the PR moves while waiting.

See the Review CI guide for prerequisites and the full try-it flow.

Why Review CI

AI coding agents can edit code, run tests, commit, push, reply, and resolve threads. What they cannot reliably do alone is know when a PR is actually ready. GitHub spreads that signal across review threads, review requests, check runs, status contexts, mergeability fields, top-level comments, and webhooks that arrive after every push. An agent dropped into a checkout sees a snapshot. Toast sees the stream.

Without Review CI, each fix-and-check cycle requires the agent to:

• Grep raw GitHub review threads via gh and parse them.
• Figure out which reviewers and checks are still pending — and which are blocking vs advisory.
• Distinguish AI-reviewer behavior (Copilot, Cursor) from human review state.
• Parse top-level comments like "looks good, merge after fixing X" that bypass GitHub's review API entirely.
• Reply to each thread in the right format with a commit link.
• Resolve every required thread after replying.
• Re-poll GitHub after each push, hoping to catch follow-up comments without missing the webhook race.
• Track the current PR head SHA across pushes so it doesn't claim ready on a stale state.
• Decide when to stop iterating.

Each step is a place an agent can spend tokens, time, and confidence — or get it subtly wrong and ship something that wasn't actually ready.

With Review CI, the agent does one thing:

toast review-ci wait --repo $ORG/$REPO --pr $N --json

When this exits 0 (status ready), the PR has cleared the review + check + mergeability gate for its current head. If it exits non-zero with status needs_fix, the JSON response includes a blocking_items array — URL, body, path, line, reviewer, and the required reply/resolve action for each item — plus agent_instructions telling the agent exactly how to respond. The agent fixes, pushes, runs wait again. That's the whole loop. (Omit --json for a human-friendly status line if you're driving the loop interactively.)

Toast does not manage agents, model tokens, worktrees, or code changes. The agent still owns the fix loop — Toast just hands it a clean contract.

Prerequisites

• Install the Toast GitHub App on the GitHub org + repo you want Review CI for. Slack install is not required — Review CI runs entirely through GitHub.
• You're an active member of the GitHub org.

(Review CI itself enables on the org automatically the first time you run toast auth; you don't need to flip anything.)

Install

npm install -g @toast-ninja/toast-cli

This installs the toast command.

Check whether the installed CLI is current:

toast update-check

If an update is available, upgrade and reinstall the agent guidance:

npm install -g @toast-ninja/toast-cli@latest && toast review-ci instructions --install

For local development from this repository:

npm install -g ./packages/toast-cli

Review CI Auth

toast auth

The default auth flow opens a browser, completes GitHub auth through Toast, and stores an org-scoped Toast token after the localhost callback returns. When run inside a GitHub checkout, toast auth infers the org from origin.

Use --org when authenticating outside a repo or when you need an explicit scope:

toast auth --org toast-ninja

You can authenticate multiple orgs on the same machine. The CLI stores tokens by org and picks the token that matches --repo:

toast auth --org toast-ninja
toast auth --org another-org
toast review-ci next --repo another-org/backend --pr 1177

If browser auth is not available, use GitHub device auth explicitly:

toast auth --device

For automation or local debugging with an existing GitHub token:

toast auth --org toast-ninja --github-token "$GITHUB_TOKEN"

That token must be a user token that can prove active membership in the org. GitHub Actions' repository GITHUB_TOKEN is not a user login token; use TOAST_TOKEN in CI.

The older toast review-ci auth --repo ORG/REPO command still works as a compatibility alias.

Review CI

toast review-ci wait \
  --repo toast-ninja/backend \
  --pr 1177 \
  --timeout 20m

wait exits 0 only when Toast returns ready for the bound PR head. If --head is omitted, Toast reconciles the current PR head first and binds the wait to that SHA. Passing --head SHA remains available for callers that already have an exact commit; exact-head callers can receive head_changed if the PR moves. It exits 1 for actionable non-green states and 2 for auth, network, argument, or timeout errors. It waits on Toast's server-side Review CI events through bounded requests, so a local polling interval is not needed. If a wait stays pending, the CLI prints the current waiting_for reason to stderr; when a bounded wait wakes from a webhook or timeout, Toast reconciles exact GitHub PR state when needed. Reconciled responses include concrete GitHub check names in github_checks / waiting_for.github_checks when CI is pending or failing. Server-side semantic triage for top-level comments is observe-only telemetry and does not change CLI readiness responses.

cursor[bot] / cursoragent[bot] advisory threads whose cited file was touched by a later commit are resolved server-side and surfaced under auto_resolvable_threads. Each entry has id, url, path, action (resolved | resolve_failed), and resolved. The field is omitted when there is nothing to report. Agents do not need to take action on these threads; they are informational and indicate housekeeping Toast did on the caller's behalf.

CI can also provide a token directly:

TOAST_TOKEN="$TOAST_TOKEN" toast review-ci status \
  --repo toast-ninja/backend \
  --pr 1177 \
  --json

Use next to fetch the actionable Review CI payload, including unresolved thread/comment URLs when Toast has enough context:

toast review-ci next \
  --repo toast-ninja/backend \
  --pr 1177

Install agent guidance from the project checkout:

toast review-ci instructions --install

This installs the Codex skill and writes a bounded Toast Review CI section to CLAUDE.md and AGENTS.md. The --install-agent flag is an alias for --install; the older --install-codex flag still installs only the Codex skill.

Or print the guidance:

toast review-ci instructions

Agent hooks (installed by default)

toast review-ci instructions --install also drops a PreToolUse hook into .claude/settings.json (Claude Code) and .codex/hooks.json (Codex CLI) in the current directory. The hook prints a stderr reminder when an agent runs gh pr checks, nudging it back to toast review-ci next/wait. It only warns — it does not block, so legitimate debug usage still works. Both files are project-scoped and committed alongside your code so teammates get the hook on checkout.

Skip the hook installation with --no-hooks:

toast review-ci instructions --install --no-hooks

To install or remove the hooks on their own without touching the markdown guidance:

toast review-ci install-hooks            # install
toast review-ci install-hooks --uninstall  # remove

Both Claude Code and Codex use the same lifecycle event names (PreToolUse / PostToolUse / Stop / etc.), so the same hook configuration works across either agent without touching the gh binary or the user's shell.

AI Agent Instructions

Use Review CI as the source of truth for PR readiness. Before using gh to rediscover review context, run:

toast review-ci next --repo ORG/REPO --pr NUMBER --json

Keep iterating until the response status is ready. For needs_fix, fix every blocking_items entry, follow agent_instructions and required_actions_policy, reply with what changed, resolve the required item kinds, push, then run:

toast review-ci wait --repo ORG/REPO --pr NUMBER --json

If wait returns ready, report completion. If it returns needs_fix, use the returned blocking_items and continue the fix loop instead of claiming the PR is done. For pending or degraded:reconciliation_incomplete, run wait and use waiting_for to see what Toast is waiting on. If Toast returns head_changed, restart the loop with next so the new PR head is evaluated.

ready is a strict backend state for the returned head SHA: required blocking reviewer participation is satisfied under policy, blocking review items and threads are clear, and Toast sees no blocking reviewer/check/mergeability wait. When reporting ready, include the returned head SHA and confidence. If the response includes readiness_certificate, github_checks, or github_mergeability, summarize those too.