@dashclaw/cli

@dashclaw/cli

Terminal client for DashClaw — approve agent actions and diagnose your instance without leaving the shell.

Install

npm install -g @dashclaw/cli

Configure

The CLI resolves config in this order:

• Environment variables (DASHCLAW_BASE_URL, DASHCLAW_API_KEY, optional DASHCLAW_AGENT_ID)
• Saved config at ~/.dashclaw/config.json (mode 600)
• Interactive prompt (first run)

On first run, if neither env vars nor a saved config are present, the CLI walks you through setup and offers to save the values to ~/.dashclaw/config.json. Env vars always override saved values.

# Option A: env vars (one-shot or CI)
export DASHCLAW_BASE_URL="https://your-dashclaw.example.com"
export DASHCLAW_API_KEY="oc_live_..."

# Option B: interactive first run (persists)
dashclaw doctor
# → DashClaw instance URL: ...
# → API key: ********
# → Save to ~/.dashclaw/config.json? [Y/n]

# Later: remove the saved config
dashclaw logout

Optionally set DASHCLAW_AGENT_ID (defaults to cli-operator) for audit attribution.

Commands

dashclaw approvals

Interactive inbox for all pending approval requests. Use arrow keys to navigate, A to approve, D to deny, O to open the replay link, Q to quit.

dashclaw approve <actionId>

Approve a single action by ID.

dashclaw approve act_01h... --reason "Verified change window"

dashclaw deny <actionId>

Deny a single action by ID.

dashclaw deny act_01h... --reason "Outside change window"

dashclaw install claude

Provision DashClaw governance into Claude Code without cloning the repo.

dashclaw install claude                          # prompts for endpoint + API key
dashclaw install claude --endpoint <url> --key <oc_live_...>
dashclaw install claude --trial                  # browser signup on a hosted instance, paste the key

Flow: preflight (/api/health + an authenticated read — nothing is written until it passes), hooks downloaded from your instance's /downloads/dashclaw-claude-code-hooks.zip (or copied from a repo checkout), python3/python resolved automatically, managed hook entries merged into ~/.claude/settings.json (.dashclaw-bak backup, replace-on-reinstall), credentials written to ~/.dashclaw/claude-hooks/.env (mode 600 — no secret lands in settings.json). Installs in observe mode; flip to enforce by setting DASHCLAW_HOOK_MODE=enforce in that .env. For --trial, set DASHCLAW_HOSTED_URL (or --endpoint) to the hosted instance if it isn't prompted.

dashclaw cost

Spend readback from GET /api/finops/spend — your own Claude Code cost or the fleet rollup, straight from the terminal.

dashclaw cost                            # Claude Code spend, last 7 days (defaults)
dashclaw cost --lens claude-code --period 30d
dashclaw cost --lens fleet --period 90d  # agent LLM cost + x402 purchases

Outputs an aligned table (total, sessions, cache savings, by-project breakdown for the Claude-Code lens; Agent LLM / x402 / Total for the Fleet lens) plus a one-line summary. Unconfigured exits non-zero with a dashclaw install claude hint; bad --lens/--period values are rejected with usage text.

dashclaw doctor

Diagnose your DashClaw instance and this machine. Remote checks cover database, configuration, auth, deployment, SDK reachability, governance, and data hygiene; local checks cover what the server can't see — a stale compiled mcp-server/lib, .gitattributes drift, a local DB schema behind code, a disabled OpenClaw runtime plugin, a stale global CLI shim, broken Claude hook installs, and leaked machine-scope DASHCLAW_* env vars.

dashclaw doctor                          # report-only (DEFAULT — applies nothing)
dashclaw doctor --fix                    # apply safe auto-fixes, re-check, report what changed
dashclaw doctor --json                   # JSON output for CI/scripts (includes local checks)
dashclaw doctor --category database,config   # filter remote checks
dashclaw doctor --repo /path/to/dashclaw     # point repo checks at a checkout
dashclaw doctor --no-fix                 # accepted no-op alias (report-only is the default)

Changed in 0.4.0: dashclaw doctor no longer applies remote auto-fixes by default — it reports and prints would-fix entries. Pass --fix to apply. Exit codes are unchanged (0 healthy, 1 otherwise).

Detect-only classes are never auto-fixed: leaked machine env vars (removal instructions printed) and OpenClaw gateway configs (remediation text printed). The .gitattributes restore runs only when the diff is provably line-ending/whitespace-only. Remote fixes go through POST /api/doctor/fix; fixes that need server filesystem access remain self-hoster territory via npm run doctor (also report-only by default now, same --fix opt-in).

dashclaw code

Subcommand group for Code Sessions (Claude Code analytics, ported from AgentLens). Three actions:

dashclaw code ingest                     # walk ~/.claude/projects and POST every .jsonl
dashclaw code ingest --dry-run           # preview the file list and payload shape without POSTing
dashclaw code ingest --projects-dir <p>  # override the default projects directory (also reads $CLAUDE_PROJECTS_DIR)

dashclaw code memo --project <slug>      # show the most recent weekly memo for a project
dashclaw code memo --project <slug> --save  # write the memo to ./memos/<iso-week>.md

dashclaw code apply <manifest-id> --dest=<project-cwd>   # apply an Optimal Files manifest locally
dashclaw code apply <manifest-id> --dest=<project-cwd> --dry-run

ingest stream-reads each session JSONL line-by-line and ships raw lines; large request bodies are brotli-compressed on the wire (via the x-dashclaw-encoding: br header — no base64 inflation) to fit Vercel's 4.5 MB per-request limit. It retries 429s and 5xxs with exponential backoff and throttles 150 ms between POSTs. Files over 40 MB raw are skipped with a too_large log entry. Never logs raw transcript content.

There is also dashclaw code ingest-codex [--dry-run], which backfills Codex CLI transcripts from ~/.codex/sessions (--sessions-dir <path> to override; --out <dir> for the local output directory).

apply fetches a manifest from /api/code-sessions/manifests/<id>, re-runs the secret scan, and writes the bundled files to --dest. Existing files get a three-way merge via the section-aware markdown merger; new files are written directly. Refuses any path outside --dest (path-traversal guard).

dashclaw install codex

Provision DashClaw governance into the Codex CLI: writes an AGENTS.md governance block into the target project and (optionally) wires Codex's notify config.

dashclaw install codex --project <path>          # default: current directory
dashclaw install codex --approval-policy on-request
dashclaw install codex --include-notify          # also wire notify → dashclaw codex notify

dashclaw codex notify '<json>'

Records a Codex turn-complete event as a DashClaw action record. Called by Codex's notify config (wired by install codex --include-notify); always exits 0 so Codex never sees an error from the spawn.

dashclaw prompts

Prompt-library client: list [--category C], get <id>, versions <id>, render <templateId> [--version-id <vid>] [--var key=value] [--record], create --name N --description D --category C (admin), add-version <id> --content C (admin), activate <id> <vid> (admin), stats [--template-id X].

dashclaw inbox

Agent message inbox: inbox list [--unread] [--limit N], inbox read <id> [...], inbox archive <id> [...].

dashclaw behavior

Behavior Learning readback: behavior status (local recorder sample counts) and behavior suggestions [--agent-id <id>] (evidence-backed policy suggestions).

dashclaw posture / dashclaw next

posture prints the governance posture score and the remediation queue; posture resolve <key> [--snooze | --accept-risk] [--note "..."] dispositions a finding. next prints the single top open governance gap and its fix.

dashclaw env

Run a command with managed secrets injected in-memory (values never touch disk or the terminal):

dashclaw env [--agent <id>] -- node my-agent.js   # inject managed secrets into the child env
dashclaw env                                      # list secret NAMES + count (never values)

Fail-closed: if the secrets fetch fails, the child is not spawned.

dashclaw logout

Remove the saved config at ~/.dashclaw/config.json.

dashclaw version

Print the CLI version (--version / -v also work).

dashclaw help

Show all commands and flags.

Exit codes

• 0 — healthy
• 1 — warnings present, failures, or the instance was unreachable

License

MIT.