`codebolt agent` commands

Everything related to running, managing, installing, and debugging agents from the command line. This is the user-level reference; the full auto-generated flag list is under Reference → CLI.

Running

`codebolt agent start`

Start a new agent run.

codebolt agent start <agent-name> --task "..."
codebolt agent start generalist --task "add a /health endpoint" --project /path/to/proj

Options:

Flag	Meaning
`--task "..."`	Free-form task description
`--input '{"key": "..."}'`	Typed input (for agents with an inputs schema)
`--project <path>`	Which project to run in (default: cwd)
`--model <name>`	Override the default model
`--watch`	Stream progress to stdout (default for interactive shells)
`--detach`	Run in background, return immediately
`--print-id`	Print the run ID and exit (useful with `--detach`)
`--json`	Print structured progress and final result as JSON
`--limits '{"max_tool_calls": 50}'`	Override budget limits
`--timeout N`	Client-side timeout in seconds

`codebolt agent watch`

Stream events from a running agent.

codebolt agent watch <run-id>
codebolt agent watch <run-id> --filter tool.*

Attaches to a running agent and streams its events. Useful after --detach, or to watch a run started from the UI.

`codebolt agent wait`

Block until a run finishes.

codebolt agent wait <run-id>

Exits when the run ends. Exit code reflects the terminal state (0 for completed, non-zero otherwise).

`codebolt agent output`

Print the final output of a completed run.

codebolt agent output <run-id>
codebolt agent output <run-id> --json

`codebolt agent stop`

Gracefully stop a run at the next phase boundary.

codebolt agent stop <run-id>

`codebolt agent kill`

Force-kill a hung run (SIGTERM, then SIGKILL). Use only if stop doesn't work.

codebolt agent kill <run-id>

Listing and inspecting

`codebolt agent list`

List installed agents.

codebolt agent list
codebolt agent list --json
codebolt agent list --scope workspace    # only workspace-local
codebolt agent list --source marketplace  # only from marketplace

`codebolt agent show`

Show the full manifest of an agent, including resolved defaults.

codebolt agent show generalist
codebolt agent show my-agent --json

Useful before remixing to see what you're inheriting from.

`codebolt agent history`

Show recent runs.

codebolt agent history
codebolt agent history --agent reviewer --limit 20
codebolt agent history --status failed --since "2026-04-01"

`codebolt agent trace`

Print the full phase-by-phase trace of a run.

codebolt agent trace <run-id>
codebolt agent trace <run-id> --phase 3
codebolt agent trace <run-id> --type llm.chat
codebolt agent trace <run-id> --json

See Testing and debugging for debugging workflows.

`codebolt agent inspect`

Open an interactive REPL into a recorded run.

codebolt agent inspect <run-id>

Step through phases, query memory-as-it-was, re-execute a phase with modified inputs, diff assembled contexts. See Testing and debugging.

Installing and publishing

`codebolt agent install`

Install an agent from a registry.

codebolt agent install marketplace/<name>
codebolt agent install marketplace/<name>@1.2.0
codebolt agent install org/<name> --registry https://codebolt.my-org.com

`codebolt agent uninstall`

codebolt agent uninstall <name>

`codebolt agent create`

Scaffold a new agent.

codebolt agent create --remix generalist --name my-reviewer
codebolt agent create --framework --name my-planner
codebolt agent create --framework --pattern unified --name my-agent

`codebolt agent publish`

Publish to a registry.

codebolt agent publish my-agent                             # public marketplace
codebolt agent publish my-agent --registry <url>            # private registry
codebolt agent publish my-agent --dry-run                   # validate without publishing

See Publishing.

`codebolt agent lint`

Validate an agent manifest and structure.

codebolt agent lint my-agent

Run before publishing. Catches missing fields, invalid schemas, unreachable entrypoints, suspicious tool allowlists.

Testing

`codebolt agent test`

Run an agent once in a sandbox.

codebolt agent test my-agent --task "..."
codebolt agent test my-agent --input '{"task": "..."}'

Does not commit file changes. Prints the phase trace.

`codebolt agent record`

Run an agent and record the full trace to a file.

codebolt agent record my-agent --task "..." --output trace.json

The recorded trace can be replayed later.

`codebolt agent replay`

Replay a recorded trace against the agent as it exists now.

codebolt agent replay trace.json
codebolt agent replay trace.json --strict   # fail on any behaviour divergence

The replay mocks LLM and tool calls with the recorded responses. Changes in your agent's logic will show up as divergences from the original trace.

`codebolt agent test-all`

Run every recorded test case for an agent.

codebolt agent test-all my-agent

Runs every *.trace.json file under my-agent/tests/ as a replay test. Exit code indicates pass/fail.

Portfolios

`codebolt agent portfolio`

Manage which agents are active in the current workspace's portfolio.

codebolt agent portfolio list
codebolt agent portfolio add <name>
codebolt agent portfolio remove <name>
codebolt agent portfolio export > portfolio.yaml
codebolt agent portfolio import < portfolio.yaml

Useful for reproducible project setups: commit portfolio.yaml to the repo and anyone who opens the project gets the same set of agents.

Delegation

`codebolt agent delegate`

Start a child run from an existing run (programmatic use).

codebolt agent delegate <parent-run-id> <child-agent> --input '...'

Creates a child run causally linked to the parent. Primarily used from inside agents via the codebolt_agent.start tool, but also available from the CLI for testing orchestration logic.

Examples

Run a reviewer in CI on every PR

set -euo pipefail
codebolt project open "$CHECKOUT_DIR"

RUN_ID=$(codebolt agent start reviewer \
  --task "review the diff against origin/main" \
  --detach --print-id)

codebolt agent wait "$RUN_ID"
codebolt agent output "$RUN_ID" --json > review.json

# Fail if the reviewer flagged issues
jq -e '.status == "approved"' review.json

Replay-test an agent before shipping

codebolt agent lint my-agent
codebolt agent test-all my-agent
codebolt agent publish my-agent --dry-run
codebolt agent publish my-agent

Find why a production run failed

codebolt agent history --status failed --limit 5
codebolt agent trace <run-id> --type llm.chat > llm-calls.txt
codebolt agent inspect <run-id>

Running​

codebolt agent start​

codebolt agent watch​

codebolt agent wait​

codebolt agent output​

codebolt agent stop​

codebolt agent kill​

Listing and inspecting​

codebolt agent list​

codebolt agent show​

codebolt agent history​

codebolt agent trace​

codebolt agent inspect​

Installing and publishing​

codebolt agent install​

codebolt agent uninstall​

codebolt agent create​

codebolt agent publish​

codebolt agent lint​

Testing​

codebolt agent test​

codebolt agent record​

codebolt agent replay​

codebolt agent test-all​

Portfolios​

codebolt agent portfolio​

Delegation​

codebolt agent delegate​

Examples​

Run a reviewer in CI on every PR​

Replay-test an agent before shipping​

Find why a production run failed​

See also​