CLI Commands

Complete reference for every Caret CLI command with flags and examples.

Overview

The Caret CLI is the primary interface for setup, supervision, and session review. Install globally with npm install -g @caret/cli.

caret <command> [options]

Initialize Caret in a project. Creates caret.config.json.

caret init [--force] [--agent <name>] [--minimal]

Authenticate with your Caret account.

caret login [--token <token>] [--check]

Install supervision hooks for an AI coding agent.

caret supervisor install --agent <name> [--global] [--force] [--dry-run]

Flag	Description	Default
`--agent`	Agent: claude-code, cursor, codex, aider	required
`--global`	Install globally for all projects	false
`--dry-run`	Preview without installing	false

Check supervisor and daemon status.

caret supervisor status [--json]

Manage the background daemon that handles hook requests.

caret daemon start [--port <number>] [--foreground] [--log-level <level>]
caret daemon stop [--force]
caret daemon status [--json]

Run an agent as a supervised subprocess.

caret run <command> [--intent <text>] [--tag <key=value>] [--no-upload] [--timeout <seconds>]

Example:

caret run claude --intent "Fix the login bug" --tag team=platform

List and inspect agent sessions.

caret sessions [--id <id>] [--limit <n>] [--status <status>] [--agent <name>] [--since <duration>] [--json] [--web]

Show health scores for projects or sessions.

caret health [--project <name>] [--period <duration>] [--breakdown] [--json]

View cost tracking data.

caret cost [--period <duration>] [--by <dimension>] [--agent <name>] [--json]

Show the file diff for a completed session.

caret diff <session_id> [--stat] [--scope] [--output <file>]

Was this helpful?