CLI Reference (pc command)

Hard-stop the rotator across CLI + VS Code + all daemons.

WHAT IT DOES:
  1. Writes ~/.power-claude/state/emergency-off (atomic tmpfile + rename)
  2. Sends SIGTERM then SIGKILL after a grace window to every
     power-claude-proxy process found via pgrep -f (equivalent to
     `pkill -f`; uses Node's process.kill so behavior is identical
     across Linux and macOS and the exit code is observable).
  3. Removes pending-recovery.json so no auto-resume fires

WHAT IT DOES NOT DO:
  • NEVER touches ~/.power-claude/profiles/ (your accounts stay)
  • NEVER touches ~/.claude/.credentials.json (your active login stays)
  • NEVER deletes state, logs, license, config, or referral data

WHEN TO USE:
  • Proxy returning 401 / 403 across many accounts
  • Cascading credential-swap failures locking VS Code tabs out
  • You want to use a single account directly without rotation
  • Any time the rotator misbehaves and you need to step out

RECOVERY: run `pc emergency-on` (or delete the sentinel manually).
EXIT CODES: 0 success / 1 sentinel write failed (FATAL — disk full / read-only state dir).

Resume the rotator after `pc emergency-off`.

WHAT IT DOES:
  1. Removes ~/.power-claude/state/emergency-off
  2. Prints the previous sentinel content (reason + timestamp) for traceability
  3. Logs the resume event to ~/.power-claude/logs/events.jsonl

AFTER RUNNING:
  • Reload VS Code (Ctrl+Shift+P → Developer: Reload Window) to restart
    the proxy that emergency-off killed. Without reload, the proxy stays
    down even though the sentinel is gone.
  • Bash hooks resume on the next claude CLI invocation automatically.

SAFE: idempotent — re-running when sentinel doesn't exist is a no-op.

Lighter-weight recovery than emergency-off — fixes 'rotator wedged' without
stopping the proxy.

WHAT IT DOES:
  • Clears throttle locks (~/.power-claude/state/*throttle*)
  • Clears refresh in-flight markers
  • Restarts the watchdog daemon
  • Resets the leader-election lock if the holder is dead

WHEN TO USE:
  • `pc rotate` says 'all accounts cooling' but cooldowns expired
  • Watchdog appears stopped but proxy still answering
  • After killing a hung `pc relogin --all`

SAFE: never deletes profiles or credentials. Use BEFORE emergency-off.

Equivalent of `emergency-off` + `fix` + a full state directory reset.

WHAT IT DOES:
  1. Sets the emergency-off sentinel
  2. Kills the proxy
  3. Clears EVERY transient file in ~/.power-claude/state/ EXCEPT the sentinel
     (rate-limits.json, watchdog locks, leader markers, refresh cooldowns)
  4. Truncates the in-flight events log

PRESERVED:
  • Profiles (~/.power-claude/profiles/)
  • Credentials (~/.claude/.credentials.json)
  • License + referral data

WHEN TO USE: ONLY when emergency-off + fix did not recover the rotator.
Last resort. Always recoverable via `pc emergency-on` + Reload Window.

Read-only diagnostic. Prints PASS/WARN/FAIL for each of 15 checks:
  • emergency-off sentinel present?
  • pc / power-claude symlinks intact?
  • PATH includes ~/.power-claude/bin?
  • Profiles directory readable?
  • Active credential file present + valid JSON?
  • Hook orphans in ~/.claude/settings.json (script paths that 404)?
  • Watchdog liveness (last tick within 5min)?
  • Proxy liveness (port 3456 listening + /health 200)?
  • events.jsonl size under cap (50MB)?
  • ANTHROPIC_BASE_URL leak (curl proxy when sentinel set)?
  • Stale ~/.vscode-server/extensions entries pointing at missing dirs?
  • Manifest version matches installed version?
  • Bash runtime scripts present in ~/.power-claude/scripts/?
  • License activation valid (offline check)?
  • Host tuning applied + no drift (exit-143 fix — see `pc tune`)?

SAFE: zero side effects. Run liberally; doctor is the first thing to
show somebody else when filing a bug report.

Run the full kill-switch contract test suite under an isolated
POWER_CLAUDE_HOME at /tmp. Tests cover:
  • sentinel write/read/delete cycle
  • atomic write under simulated interrupt
  • permission-denied recovery
  • path-traversal defense (UUID regex on session ids)
  • events.jsonl 50MB rotation cap
  • on/off idempotency
  • bash + Node fallback parity
  • daemon mid-loop sentinel checks

SAFE: never touches your real ~/.power-claude/. Locks in the operator-
facing contract — if a future refactor breaks any test, this fails loudly.

Score every configured account, pick the highest-scored healthy one,
and atomically swap ~/.claude/.credentials.json to it.

SCORING (score.sh / accountSelector parity):
  healthy=100 / refreshable=90 / cooling=80 / refresh-deferred=70 /
  blocked=60 / error-recovered=50 / cooling-active=0 / expired=-1

TIE-BREAK: subscriptionType (max < pro < unknown), then lastHealthy desc.
PRE-EMPTIVE: accounts at >=98% quota are skipped regardless of health.

WRITES:
  • ~/.claude/.credentials.json (atomic via tmp+rename, mode 0600)
  • ~/.power-claude/state/active-account.json (mirror)
  • ~/.power-claude/state/rate-limits.json (lastSwap timestamp)

RESPECTS emergency-off: refuses to rotate, exits non-zero.

Force the active account to <name> bypassing the scorer.

USE WHEN:
  • Scorer keeps picking the wrong account (e.g. you want pro tier even
    though a max account is healthy)
  • Testing a specific account in isolation
  • Recovering after a wrong-account swap

WRITES the same files as scored rotate. Validates that <name> exists
in ~/.power-claude/profiles/<name>.json — refuses if missing.

RESPECTS emergency-off.

Same as `pc rotate <name>` — sets the active account without going
through the scorer. The two names exist for muscle-memory reasons:
  • `rotate` reads as 'cycle to a new one'
  • `switch` reads as 'I want THIS one'
Both call the same code path.

Add <name> to ~/.power-claude/config/pinnedAccounts. The scorer
filters its candidate pool to pinned accounts when any are present
(falls back to the full pool if all pinned accounts are unhealthy).

USE TO:
  • Reserve max-tier accounts for heavy work
  • Park experimental accounts so they don't burn quota
  • Stage a controlled rollout to a subset of profiles

Idempotent — pinning an already-pinned account is a no-op.
Inverse: `pc unpin <name>`.

Inverse of `pc pin`. Removes <name> from pinnedAccounts. If the list
becomes empty, the scorer's full candidate pool is restored.

Tags appear in `pc list` and in the dashboard accounts table. Use them
to mark accounts by project / client / tier / quota schedule.
Free-form strings; no schema enforced.

Inverse of `pc tag`. Removes a single label; other labels on the
account are untouched.

Writes ~/.power-claude/state/rotation-disabled (sentinel checked by
watchdog + handler). The proxy keeps serving, but a 429 from the
current account will NOT trigger an account swap — the request just
fails and the user sees the rate-limit response.

USE WHEN:
  • Debugging a quota issue and you want predictable single-account behavior
  • Testing rate-limit handling end-to-end
  • The user explicitly wants to burn one account before swapping

SAFE: never touches credentials or profiles.

Removes ~/.power-claude/state/rotation-disabled. The next 429 will
trigger normal scored rotation again. Idempotent.

Read-only check. Prints 'ENABLED' or 'DISABLED (since <timestamp>)'.
Reads the rotation-disabled sentinel; safe to run repeatedly.

Flat alias for `pc disable`. Touches ~/.power-claude/state/rotation-disabled.
The proxy keeps running but never flips active account on 429 — every
request goes to whichever account ~/.claude/.credentials.json points at.
Reverse: `pc rotation-on` or `pc enable`.

Flat alias for `pc enable`. Removes the rotation-disabled sentinel.
The next 429 / score-drop will trigger a normal scored rotation.

Distinct from `emergency-off` (which kills the proxy) and `rotation-off`
(which pauses account selection). `pc cli off` un-shims the `claude`
binary in your shell so the CLI talks to api.anthropic.com directly,
while the proxy stays up to serve your IDE windows. Useful when you
want to debug the proxy WHILE staying productive in the terminal.

Subcommands:
  pc cli off     Disable bash auto-routing (claude → upstream directly)
  pc cli on      Re-enable bash auto-routing
  pc cli status  Show whether bash auto-routing is currently active

Pretty-prints every profile in ~/.power-claude/profiles/ as a table:
name, subscriptionType, status, lastHealthy, quota%, tags.
Read-only. The dashboard's Accounts table shows the same data live.

Interactive prompt for profile name + OAuth flow. Validates the name
with assertSafeName (rejects path traversal), opens browser for OAuth,
writes ~/.power-claude/profiles/<name>.json with mode 0600.

Prefer `pc save-profile` if you already have ~/.claude/.credentials.json
from a manual `claude login` and just want to capture it as a profile.

Re-runs OAuth for one or every saved profile. Use when:
  • Refresh token expired (ensureTokenFresh fails)
  • Account was disconnected from claude.ai
  • You changed account passwords / MFA

Opens browser for each account in turn. `--no-prompt` runs without
interactive prompts (for scripted relogin sweeps). `--no-restore`
leaves the previously-active account inactive after the OAuth
exchange — useful when you intend to flip away immediately.

Reads ~/.claude/.credentials.json and writes it as a Power Claude
profile at ~/.power-claude/profiles/<name>.json (mode 0600).

USE WHEN:
  • You ran `claude login` directly and now want to add it to rotation
  • Migrating from a single-account setup to multi-account
  • Capturing a fresh OAuth state after a manual relogin

With --stdin, reads JSON from stdin instead of disk — for scripted
profile additions without exposing tokens via shell history.
Validates name with assertSafeName (path-traversal defense).

DESTRUCTIVE: removes ~/.power-claude/profiles/<name>.json from disk.
If <name> was the active account, also clears the .active pointer in
rate-limits.json so the watchdog won't loop logging 'ACTIVE EXPIRED'.
Does NOT log out of claude.ai — only removes the local profile copy.
Recovery: re-add via `pc relogin <name>` or `pc add`.

Bundles every profile in ~/.power-claude/profiles/ into a single
self-describing blob (JSON + CRC32 checksum). Safe to email / paste
into a private gist — credentials are NOT additionally encrypted, so
treat the blob as you would a password file.

RUN BEFORE: mass relogin, --purge uninstall, OS reinstall.

Inverse of export. Verifies CRC32 before any disk write — corrupt
blobs are rejected with a checksum mismatch error.

Refuses to overwrite existing profiles unless --force is given.

Prints the absolute path to your ~/.power-claude/ data tree. Honors
the POWER_CLAUDE_HOME env var when set (test/mock scenarios).
Use this to find your data when troubleshooting backups or scripting
external archive jobs.

Walks ~/.power-claude/ and reports byte size per top-level subtree.
Read-only. Useful before a `pc data backup` (to estimate archive
size) or when investigating why the install footprint grew.

Creates a gzipped tar of state/, profiles/, logs/, config/. Skips
cache/ and run/ (transient — regenerated on next proxy start).

WHERE: defaults to ~/.power-claude/backups/manual-<ISO>.tar.gz.
Pass --out PATH to choose an arbitrary destination (e.g. an
external drive or shared filesystem before a wipe).

Use BEFORE: relogin --all, --purge uninstall, OS reinstall, or
any risky maintenance you want to be able to roll back from.

Extracts a `pc data backup` archive over ~/.power-claude/. BEFORE
extraction, auto-snapshots the CURRENT state to backups/
pre-restore-<ISO>.tar.gz so the restore itself is reversible.

Refuses to proceed without --force when current data exists
(prevents accidental overwrite). The pre-restore snapshot path is
printed so you can re-restore that if the new archive turns out
to be the wrong one.

Shorthand for `pc data backup` with an auto-labeled filename:
backups/snapshot-<ISO>.tar.gz. Used internally by `pc install` and
`pc migrate` as a pre-flight; runnable manually as a checkpoint
before risky work.

Read-only check. Parses every profile JSON, rate-limits.json,
proxy-status.json, license.json, and counts samples in
usage-history.jsonl + the .archive.jsonl.gz companion.

Reports invalid files by name and exits 1 if any errors found.
Run after a restore, after a power-loss reboot, or whenever the
dashboard looks empty for unclear reasons.

OPT-IN ONLY. Filters usage-history.jsonl and events.jsonl to keep
lines with timestamps within the last N days. Older lines are
dropped. ALWAYS auto-snapshots first (backups/pre-prune-<ISO>.tar.gz)
so this is reversible.

WHEN: disk pressure, slow dashboard renders on >100k lines.
NEVER runs by default — `pc install` does NOT call this.

Boots the rotating proxy on 127.0.0.1:8118 (default). The proxy
listens for Anthropic API requests, scores accounts, swaps active
credential on 429, and refreshes OAuth tokens transparently.

RESPECTS emergency-off: refuses to start if sentinel present.
Normally invoked by the VS Code extension — manual `pc serve` is
for headless deployments or debugging.

Read-only snapshot of every account's score, status, quota, and the
currently-active account. Prints once and exits — for the live TUI
version, use `pc watch`.

Curses-style live dashboard. Hotkeys:
  s     — switch account interactively
  r     — rotate (pick next healthy)
  R     — relogin selected account
  jk    — move selection up/down
  Enter — drill into selected account's events
  Esc   — back to dashboard
  q     — quit

Reads the same files as `pc status` but refreshes every 1s.

Power Mode dispatches each request to the LEAST-LOADED account in a
configured pool — so long-running operations (full repo scans, batch
completions) finish faster by running in parallel across multiple
accounts simultaneously.

Subcommands:
  status      — show pool members + per-account inFlight
  on / off    — enable / disable Power Mode
  add ACCT    — include ACCT in the pool
  remove ACCT — exclude ACCT from the pool
  configure   — interactive pool + concurrency setup
  config      — print parallel-mode config keys

MODES:
  least-utilized (default) — pick lowest weight (5h util + inFlight*0.01)
  round-robin              — strict cycle through pool

Sends a /v1/messages no-op probe to every account in parallel,
measures latency + status, and renders a colored table. Use to:
  • Verify all accounts are reachable after a network change
  • Find the fastest account to pin
  • Confirm an account that the scorer thinks is `error` is actually
    healthy (and call markHealthy via `pc fix`)

Costs 1 token per account (the no-op response is empty).

Reads ~/.power-claude/logs/events.jsonl (capped at 50MB by rotation).
Every component logs structured events here: rotations, refreshes,
rate-limit hits, sentinel transitions, errors.

Common invocations:
  pc logs --follow                    # tail live
  pc logs --level error --since 1h    # recent errors
  pc logs --component proxy --tail 50 # last 50 proxy events
  pc logs --json | jq                 # machine-readable for scripts

Wrapper that runs `claude` with the rate-limit hook chain attached.
On 429, the hook auto-rotates accounts and resumes the same session
transparently — no manual intervention needed.

Pass-through: everything after `--` is forwarded verbatim to claude.
Example:  pc run -- --resume <session-id>

Bootstrap the rotator on a fresh machine. Steps:
  1. PRE-FLIGHT auto-snapshot of existing ~/.power-claude/ data to
     backups/pre-install-<ts>.tar.gz (no-op on fresh installs)
  2. Creates ~/.power-claude/ directory tree (state/profiles/logs/...)
  3. Symlinks ~/.power-claude/bin/{pc,power-claude} → installed cli.js
  4. Adds ~/.power-claude/bin to PATH in your shell rc
     (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish — auto-detected)
  5. Deploys bash runtime scripts (lib/, hooks/, emergency/) into the
     tree so the proxy + watchdog have an executable copy
  6. Applies host tuning (the exit-143 grace-time fix — see `pc tune`)

NEVER touches state/, profiles/, or logs/ — pre-existing data is
preserved verbatim. The sticky trial mirror at
$XDG_CONFIG_HOME/power-claude/trial.json (typically
~/.config/power-claude/trial.json) ALSO survives every install
and even a --purge uninstall — so reinstalling never resets your
trial countdown. Re-running upgrades the deployed scripts.

Removes the install footprint (bin symlink + PATH line + hook entries
in ~/.claude/settings.json). Data is preserved by default.

Destructive flags (mutually exclusive):
  --purge          Delete the entire ~/.power-claude/ tree
  --profiles-only  Delete profiles/ only — keeps all telemetry
  --state-only     Delete state/ only — keeps profiles + history

Any destructive flag auto-snapshots current data BEFORE deletion
to ~/.power-claude/backups/ (or to ~/ for --purge so the file
survives the tree wipe). Interactive callers must type 'yes' to
confirm. Non-TTY callers (CI, scripts, --json) MUST also pass
--force.

One-time migration for users upgrading from the early rotator that
stored its data under ~/.claude/. COPIES (does NOT move) profiles,
state, and logs to ~/.power-claude/. Legacy files are left in place
so users can roll back by uninstalling the new tree.

Idempotent — re-running skips files that already exist at the new
location. Pass --overwrite to force re-copy (last-write-wins).
Lock-protected against multi-window races via leader election.

Fixes the bug where many Claude Code sessions die at once with
'exited with code 143'. Claude runs as a child of the VS Code /
code-server extension host; when the browser disconnects past a
grace period the host is disposed and every child `claude` is
SIGTERM-killed together.

`pc tune` raises the long-grace env var (VSCODE_RECONNECTION_
GRACE_TIME) to 24h via a systemd drop-in + server-env-setup block,
and lifts the bundled 5-minute short-grace cap by patching the
vendored server JS (.pcbak backups kept). The extension re-applies
the patch automatically after any code-server / VS Code update.

Idempotent. --status reports drift; --revert restores backups.
Takes effect after `systemctl --user restart code-server`.

Claude Code's webview ships every focused editor file as a content
block on every prompt by default. A typical 800-line PHP file is
~12K tokens — $0.18/turn on Opus input pricing, ~$10.80/dev/day on
a 60-turn workday. Worse, the model conditions on whatever's in
focus, so unrelated context (nginx.conf, README) degrades answers.

`pc chip-default-off` patches the bundled webview/index.js to flip
the chip's initial useState to false. Users still click the chip
to include the file — default-OFF, not removed. Stamps a 'Power
Claude feature' badge into the chip area via the brand-stamp lib.

Idempotent. The extension activate() hook re-applies after every
Claude Code upgrade — no manual re-run needed.
Reload the webview to pick up: "Developer: Reload Webviews".

Prints the value of <key> from ~/.power-claude/config/. Common keys:
  switchThreshold       — quota % at which to pre-emptively rotate (0.98)
  pinnedAccounts        — JSON array of pinned account names
  pinnedTiers           — JSON array of pinned tiers (max/pro)
  parallelMode          — 'least-utilized' or 'round-robin'
  parallelMaxConcurrent — per-account inFlight cap in Power Mode
  proxyPort             — proxy bind port

Sets <key> to <val>. Validated against the config schema —
type-mismatch keys are rejected. Atomic write.

Read-only dump of every config key + current value. Read in priority
order: defaults < ~/.power-claude/config/ < env overrides.

Activates a Neural-LLM license key against the activation server.
Consumes one machine slot per active key. Cached in ~/.power-claude/
license/state.json with periodic re-validation.

Frees the machine slot consumed by `activate`, so you can re-activate
on a different machine without buying another seat. Idempotent.

Read-only. Shows tier, expiry, machine fingerprint, last validation
timestamp. Reads cache; does NOT contact the activation server.

Same as `pc license info`.

Prints your personal referral URL and the total credit earned from
referred signups. Read-only.

Walks ~/.claude/projects/*/ and prints one row per session.
Use --failed to show only sessions with a detected failure scope.
Use --scope to filter by a specific scope (compact-thrash, tool-loop,
context-overflow, crashed, rate-limit-stuck, …). Read-only.

Detects the session's failure scopes, picks the default strategy
(or use --strategy), takes a working-tree snapshot, and executes
the recovery. Strategies: context-trim-resume, fork-from-checkpoint,
tool-rerun, pending-task-injection, naive-resume, manual-export.

Generates a markdown summary (title, todos, files touched, last 5
exchanges) suitable for pasting into a fresh Claude session as a
context seed. Defaults to ~/.claude/temp/recovery/.

Produces a .tar.gz containing the JSONL transcript, recovery history,
and a git bundle of all refs/power-claude/sessions/<id>/* refs. Restore
with `pc session restore` on another machine.

Extracts the bundle into ~/.claude/projects/, unbundles git refs,
and prints `claude --resume <id>` to continue the work. Idempotent.

DESTRUCTIVE — `git reset --hard` to the refs/power-claude/sessions/<id>/
pre-recovery-<n> ref. Use this when a recovery made things worse.
Defaults to the most recent attempt.

Prints the chronological list of every recovery attempted for the
session: strategy, outcome, snapshot refs, tokens rescued, errors.