@dashclaw/cli 0.3.1 → 0.4.0

package/README.md

@@ -57,18 +57,46 @@ 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.
+
+```bash
+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.
+
+```bash
+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 auto-fix safe issues. Checks database, configuration, auth, deployment, SDK reachability, and governance.
+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.
 
 ```bash
-dashclaw doctor                          # rich terminal output, auto-fix what it can
-dashclaw doctor --json                   # JSON output for CI/scripts
-dashclaw doctor --no-fix                 # diagnose only
-dashclaw doctor --category database,config
+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)
 ```
 
-The CLI invokes your instance's `/api/doctor` endpoints, so fixes that need filesystem access (env writes) are handled separately by self-hosters running `npm run doctor` locally.
+> **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`
 
@@ -86,10 +114,61 @@ dashclaw code apply <manifest-id> --dest=<project-cwd>   # apply an Optimal File
 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 gzip-compressed on the wire (raw gzip via the `x-dashclaw-encoding: gzip` 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.
+`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.
+
+```bash
+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):
+
+```bash
+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.