CLI Reference

July 6, 2026 · View on GitHub

Codex Skills

These are the primary commands for Codex App and Codex CLI users:

Which entrypoint should I use?

Goal	Best entrypoint	Notes
First-time setup	`@ATeam build my team` or `$ateam:init`	Use the natural-language prompt for the quickest first run; use the skill when you want explicit setup behavior.
Run the team on a task	`@ATeam <task>` or `$ateam:run "task"`	Natural-language `@ATeam` requests route to the appropriate skill; `$ateam:run` is the explicit pipeline command.
Talk to one specialist	`@Architect`, `@Dev`, `@Reviewer`, etc.	Use direct role mentions for focused work that does not need the full pipeline.
Debug or automate internals	`agenteam-rt ...`	Runtime commands expose JSON planning, policy, state, and runner primitives.

Command	Purpose
`$ateam:init`	Set up team config and generate agents
`$ateam:run "task"`	Run the full pipeline on a task
`$ateam:resume`	Resume an interrupted run
`$ateam:status`	Show team status and current config
`$ateam:add-member`	Add a custom team member
`$ateam:generate`	Regenerate agents after config changes
`$ateam:standup`	Quick project status report
`$ateam:assign <role> "task"`	Assign a task to a specific role
`$ateam:ci-repair <pr-or-branch>`	Fix CI failures — fetch logs, dispatch dev, verify, push
`$ateam:share-config`	Promote local config to shared team config

Runtime CLI

The runtime CLI (agenteam-rt) is the underlying engine. Skills call it internally, but you can use it directly for automation or debugging.

Most runtime commands are JSON planning and policy primitives: they resolve config, update state, record gates, or describe what should happen next. agenteam-rt run is the exception: it is the local executor facade. It composes those primitives, builds prompts, invokes codex exec, writes .agenteam/runs/<run-id>/ artifacts, and streams JSONL runner events.

Config & Validation

# Validate config
agenteam-rt validate
agenteam-rt validate --format diagnostics    # full structured output
agenteam-rt validate --strict                # treat warnings as errors

# Diagnose local Codex compatibility (config optional)
agenteam-rt doctor
agenteam-rt doctor --strict                  # fail on warnings or errors
agenteam-rt doctor --codex-bin /path/to/codex

# Migrate legacy config to canonical format
agenteam-rt migrate --dry-run                # preview changes
agenteam-rt migrate                          # apply migration

doctor reports version and feature discovery plus an additive capabilities object. capabilities.structured_output records support for --output-schema and --output-last-message; these become readiness errors when project config enables structured_handoffs. capabilities.hooks reports whether Codex exposes and enables lifecycle hooks. Disabled hooks are informational because AgenTeam does not currently bundle hook commands.

Roles

# List all resolved roles
agenteam-rt roles list

# Show a specific role's config
agenteam-rt roles show dev

Pipeline Operations

# Initialize a run
agenteam-rt init --task "add auth" --profile quick

# Initialize a run with optional governance metadata
agenteam-rt init --task "billing revamp" --profile standard \
  --initiative "billing-platform" --phase "requirements" \
  --checkpoint "kickoff" --burn-estimate 16

# Dispatch a stage
agenteam-rt dispatch implement --task "add auth" --run-id <id>

# Check run status for latest compatible local run
# Includes a memory block with concise carry-forward lessons from
# compatible prior runs when available
agenteam-rt status

# Check run status for a specific run
agenteam-rt status <run-id>

# Show diagnostic trace for a run
agenteam-rt trace --run-id <id>
agenteam-rt trace --run-id <id> --stale-threshold-minutes 30

# Build portable run evidence for CI repair, release review, and benchmarks
agenteam-rt evidence --run-id <id>
agenteam-rt evidence --run-id <id> --output .agenteam/evidence/<id>.json

# Create, populate, and report an evidence-backed benchmark matrix
agenteam-rt benchmark init-results --suite path/to/suite.yaml \
  --strategy single_agent --strategy native_high_effort \
  --strategy minimal_team --strategy governed_pipeline \
  --output path/to/results.json
agenteam-rt benchmark record --suite path/to/suite.yaml \
  --results path/to/results.json \
  --evidence .agenteam/evidence/<id>.json \
  --task-id <task-id> --strategy minimal_team --quality-score 0.85 \
  --model <exact-model-id> --reasoning-effort <accepted-value> \
  --codex-version <exact-version> --repo-commit <git-sha>
agenteam-rt benchmark report --suite path/to/suite.yaml \
  --results path/to/results.json --markdown-out path/to/report.md

# Export role/workflow definitions as a workspace-agent draft
agenteam-rt export workspace-agent
agenteam-rt export workspace-agent --format markdown \
  --output docs/agenteam-workspace-agent.md

# Get verification plan for a stage
agenteam-rt verify-plan implement --run-id <id>

# Record verification result
agenteam-rt record-verify --run-id <id> --stage implement --result pass

# Get final verification plan
agenteam-rt final-verify-plan --run-id <id>

# Build the fully composed prompt for a role dispatch (for codex exec / harnesses)
agenteam-rt prompt-build --run-id <id> --stage implement --role dev

# Run the full pipeline non-interactively via the local executor facade
agenteam-rt run --task "add user auth" --auto-approve-gates
agenteam-rt run --task-file seed.md --profile standard --output-dir ./out
agenteam-rt run --run-id <id>  # resume an existing run

agenteam-rt run treats non-zero role exits as stage failures, retries failed verification up to the persisted max_retries budget, blocks on human/reviewer/QA gates unless --auto-approve-gates is set, and runs final verification before marking the run completed. The runner streams Codex JSONL, persists thread IDs and heartbeats, enforces configurable wall/idle limits, resumes interrupted threads with codex exec resume, and audits role write scopes before accepting results. It invokes Codex with --sandbox workspace-write by default and passes resolved role model settings only when --codex-args does not provide an explicit normalized override. Attempt metadata and the effective model/reasoning settings are retained in state and exec.json evidence.

Seeded benchmark pilot

The repository-level pilot wrapper compares single_agent, native_high_effort, minimal_team, and governed_pipeline on the same seeded task. It pins Codex/model settings, creates detached worktrees, captures native JSONL and AgenTeam run evidence, and delegates final validation and Markdown generation to the benchmark runtime commands above.

# Validate and inspect the no-model plan
python3 scripts/benchmark-pilot.py validate \
  --manifest benchmarks/pilot/manifest.yaml
python3 scripts/benchmark-pilot.py dry-run \
  --manifest benchmarks/pilot/manifest.yaml

# After the harness is merged: prepare, execute/resume all cells, and finalize
python3 scripts/benchmark-pilot.py execute \
  --manifest benchmarks/pilot/manifest.yaml

# Recovery: inspect state, resume one cell, or clean disposable worktrees
python3 scripts/benchmark-pilot.py inspect \
  --manifest benchmarks/pilot/manifest.yaml
python3 scripts/benchmark-pilot.py run \
  --manifest benchmarks/pilot/manifest.yaml --strategy governed_pipeline
python3 scripts/benchmark-pilot.py cleanup \
  --manifest benchmarks/pilot/manifest.yaml

Local state and artifacts are under .agenteam/benchmarks/<pilot-id>/. Completed strategies are not rerun; incomplete AgenTeam runs retain their run ID for resume. Cleanup removes only clean worktrees and reports dirty ones as preserved. The pinned Codex 0.137.0 pilot records GPT-5.6 Sol as unavailable and uses GPT-5.5 xhigh for native_high_effort; validation fails closed if the live version, model, or reasoning catalog drifts. The deterministic score is 1.0 only for a successful terminal execution plus passing postcheck, else 0.0. Do not publish performance claims from an unmerged branch or before the report marks the matrix ready_for_executor_decision.

Governed Delivery Foundations

# Scaffold local governed-delivery assets
agenteam-rt governed-bootstrap

# Append a structured decision record
agenteam-rt decision append \
  --outcome escalated \
  --summary "Auth migration requires DBA approval" \
  --initiative "platform-auth" \
  --phase "triage" \
  --role architect \
  --decision-right "schema-change" \
  --artifact-type adr \
  --artifact-ref docs/decisions/012-auth-migration.md

# List decisions (optionally filtered)
agenteam-rt decision list --initiative platform-auth --last 10

# Render Markdown decision log from structured records
agenteam-rt decision render-log

# Evaluate tripwires against changed paths or artifact context
agenteam-rt tripwire check --path src/auth/login.py
agenteam-rt tripwire check --artifact-type adr --decision-right schema-change

# Record a tripwire result into a run's governance context
agenteam-rt tripwire check --run-id <id> --stage implement \
  --path src/auth/login.py

When run-scoped governance signals exist, status, status --progress, standup, trace, and evidence include governance.adoption: compact counts plus recent decision records, tripwire checks, gate rejections, criteria overrides, and open follow-ups.

Branch & Isolation

# Resolve branch/worktree plan for a task
agenteam-rt branch-plan --task "add auth" --role dev

# Check write scope overlaps
agenteam-rt policy check

# Audit changed files against write scopes
agenteam-rt scope-audit --run-id <id> --stage implement --baseline <sha>

Gates & Transitions

# Evaluate gate criteria
agenteam-rt gate-eval --run-id <id> --stage implement

# Record gate decision
agenteam-rt record-gate --run-id <id> --stage implement \
  --gate-type human --result approved

# Validate and apply stage transition
agenteam-rt transition --run-id <id> --stage implement --to passed

Events & Resume

# Append an event
agenteam-rt event append --run-id <id> --type stage_dispatched \
  --data '{"roles": ["dev"], "isolation": "branch"}'

# List events
agenteam-rt event list --run-id <id> --type stage_verified --last 5

# Detect stale resumable runs
agenteam-rt resume-detect

# Build resume plan
agenteam-rt resume-plan --run-id <id>

Reports & Health

# Assemble run report
agenteam-rt run-report --run-id <id>

# Show runtime/project readiness
agenteam-rt health

# Show Codex version/features and effective model-pin diagnostics
agenteam-rt doctor

# Assemble standup summary with current health, dispatch hints, and
# compatible carry-forward memory
agenteam-rt standup

# Generate .codex/agents/*.toml from config
agenteam-rt generate

HOTL Integration

# Check HOTL availability
agenteam-rt hotl check

# Resolve HOTL skill eligibility for a role
agenteam-rt hotl-skills --run-id <id> --stage implement --role dev

Output Format

All runtime commands output JSON to stdout. Errors go to stderr as JSON. Exit code 0 = success, 1 = error. For agenteam-rt run, stdout is a JSONL event stream rather than a single JSON object.