CLI reference

caw installs two console scripts: caw (the main multi-command app) and caw-traj (a standalone trajectory inspector, also available as caw traj).

caw

Top-level commands: doctor (provider health), auth (Docker credentials), viewer and traj (trajectory viewer).

caw

Coding Agent Wrapper — tools for managing coding agents.

Usage

caw [OPTIONS] COMMAND [ARGS]...

Arguments

No arguments available

Options

Name	Description	Required	Default
--install-completion	Install completion for the current shell.	No	-
--show-completion	Show completion for the current shell, to copy it or customize the installation.	No	-
--help	Show this message and exit.	No	-

Commands

Name	Description
viewer	Launch the trajectory viewer web UI.
doctor	Show health/availability signals for each...
traj	Inspect a saved trajectory from the terminal.
auth	Manage credentials for Docker containers.
config	View and edit caw's per-provider model...

Subcommands

caw viewer

Launch the trajectory viewer web UI.

Usage

caw viewer [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
-h, --host TEXT	Host to bind to.	No	0.0.0.0
-p, --port INTEGER	Port to bind to (0 = auto).	No	0
--help	Show this message and exit.	No	-

caw doctor

Show health/availability signals for each provider's CLI.

Usage

caw doctor [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
--live	Round-trip a probe per provider to check it responds / isn't rate-limited (costs a request each).	No	-
--help	Show this message and exit.	No	-

caw traj

Inspect a saved trajectory from the terminal.

Usage

caw traj [OPTIONS] PATH

Arguments

Name	Description	Required
PATH	Path to the saved trajectory JSON file.	Yes

Options

Name	Description	Required	Default
-s, --step TEXT	Show full details for visible-step selectors like 7, 7-10, or 12/3-12/7. Repeat to add more selectors.	No	-
-r, --recursive	Include nested visible subagent steps in the compressed listing.	No	-
--text-chars INTEGER RANGE	Maximum characters to show in user/assistant previews.	No	60; x>=10
--input-chars INTEGER RANGE	Reserved for future tool-detail rendering; accepted for compatibility.	No	60; x>=10
--help	Show this message and exit.	No	-

caw auth

Manage credentials for Docker containers.

Usage

caw auth [OPTIONS] COMMAND [ARGS]...

Arguments

No arguments available

Options

Name	Description	Required	Default
--help	Show this message and exit.	No	-

Subcommands

caw auth setup

Snapshot credentials and write the container setup bundle into ~/.caw/auth/.

Host credential files are not modified; they are bind-mounted into the container at run time via caw auth docker-flags.

Usage

caw auth setup [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
-a, --agents TEXT	Agents to include (claude, codex, or all)	No	-
--source-home TEXT	Source home directory to read credentials from	No	/home/runner
--help	Show this message and exit.	No	-

caw auth teardown

Remove ~/.caw/auth/. Host credential files are untouched.

Refuses to run if host credentials are still symlinks into the auth directory (leftover from the old symlink-based design). Use --force to override — but you will have to re-authenticate every agent.

Usage

caw auth teardown [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
-n, --dry-run	Show what would be done	No	-
-f, --force	Delete even if host symlinks point into the auth dir	No	-
--help	Show this message and exit.	No	-

caw auth status

Show token expiry, last modified, and docker mount flags.

Usage

caw auth status [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
-a, --agents TEXT	Agents to show	No	-
--help	Show this message and exit.	No	-

caw auth docker-flags

Output the -v flags for docker (one per bind mount, space-separated).

Usage

caw auth docker-flags [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
--help	Show this message and exit.	No	-

caw config

View and edit caw's per-provider model configuration (~/.caw/config.json).

Usage

caw config [OPTIONS] COMMAND [ARGS]...

Arguments

No arguments available

Options

Name	Description	Required	Default
--help	Show this message and exit.	No	-

Subcommands

caw config list

Show the effective model for every provider/tier, with its source.

Usage

caw config list [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
--help	Show this message and exit.	No	-

caw config get

Print the effective model for a single PROVIDER and TIER.

Usage

caw config get [OPTIONS] PROVIDER TIER

Arguments

Name	Description	Required
PROVIDER	[required]	No
TIER	[required]	No

Options

Name	Description	Required	Default
--help	Show this message and exit.	No	-

caw config set

Set the model for PROVIDER/TIER, saved to ~/.caw/config.json.

Usage

caw config set [OPTIONS] PROVIDER TIER MODEL

Arguments

Name	Description	Required
PROVIDER	[required]	No
TIER	[required]	No
MODEL	[required]	No

Options

Name	Description	Required	Default
--help	Show this message and exit.	No	-

caw config unset

Remove a user override for PROVIDER/TIER (revert to the default).

Usage

caw config unset [OPTIONS] PROVIDER TIER

Arguments

Name	Description	Required
PROVIDER	[required]	No
TIER	[required]	No

Options

Name	Description	Required	Default
--help	Show this message and exit.	No	-

caw config path

Print the path to the user config file.

Usage

caw config path [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
--help	Show this message and exit.	No	-

caw config refresh

Force a re-fetch of the remote default models into the local cache.

Usage

caw config refresh [OPTIONS]

Arguments

No arguments available

Options

Name	Description	Required	Default
--help	Show this message and exit.	No	-

caw-traj

The standalone trajectory inspector. Prints a compact, step-indexed view of a saved trajectory and can expand individual steps.

caw-traj

Inspect a saved trajectory.

Running caw-traj PATH prints a compact, step-indexed view of the conversational trajectory so another agent can see the structure quickly. Tool calls are omitted from the compressed view.

Use --step to retrieve full content for a specific visible step. Step paths use the same addresses shown in the compact output:

• 7 means top-level step 7
• 12/3 means nested visible step 3 under step 12
• 7-10 expands to steps 7, 8, 9, 10
• 12/3-12/7 expands to a nested range within the same parent
• you can copy the bracketed form directly, for example --step [12/3]
• multiple selectors can be combined in one flag, for example --step 7,8,12/3-12/5

Each compressed step shows a 1-based raw JSON line range like L41-L48. LLM agents should feel free to inspect the raw JSON file directly with those line numbers when the compact view is not enough.

Examples: caw-traj run.json caw-traj run.json --recursive caw-traj run.json --step 7 caw-traj run.json --step 7-10 caw-traj run.json --step 12/3 caw-traj run.json --step 12/3-12/7 caw-traj run.json --step 7,8,12/3-12/5

Usage:

caw-traj [OPTIONS] PATH

Options:

  -s, --step TEXT              Show full details for visible-step selectors
                               like 7, 7-10, or 12/3-12/7.
  -r, --recursive              Include nested visible subagent steps in the
                               compressed listing.
  --text-chars INTEGER RANGE   Maximum characters to show in user/assistant
                               previews.  [default: 60; x>=10]
  --input-chars INTEGER RANGE  Reserved for future tool-detail rendering;
                               accepted for compatibility.  [default: 60;
                               x>=10]
  --help                       Show this message and exit.