`@mushi-mushi/cli`

Project setup, report triage, agentic fix dispatch, QA coverage, skill pipelines, and headless merge — all from the terminal.


npm install -g @mushi-mushi/cli
 
mushi login
mushi connect --project-id <uuid> --endpoint <url> --wait
mushi doctor --server --qa-stories
mushi reports list --status new
mushi fix <reportId> --agent cursor_cloud --wait
mushi fixes merge <fixId>          # squash-merge the PR + mark report Fixed

Two key types: SDK ingest keys (report:write) are minted on Setup → Verify or Projects → Generate API key. Admin / MCP keys (mcp:read or mcp:write) are also minted on Projects — use mcp:write for fix dispatch, merge, and most CLI admin commands. Settings → API Keys (BYOK) is for your own LLM/Firecrawl keys, not Mushi credentials.

Console ↔ CLI setup loop

See the full walkthrough: CLI ↔ console loop.

Step	Console	CLI
Create project	Setup → Steps or Projects → New project	Wizard opens `?setup=cli`
Copy Project ID	Success panel UUID chip	`mushi init --project-id <uuid>`
Mint ingest key	Setup → Verify → Generate API key	Paste at prompt or `MUSHI_API_KEY=…`
Wire repo	SDK install configurator	`mushi init` or `mushi connect --wait`

Console URL resolution: MUSHI_CONSOLE_URL → saved config → localhost :6464 probe → hosted default.

Setup & health

Command	Purpose
`mushi init`	Wizard: prerequisite step, framework detect, install SDK, write `.env.local`, whoami verify, optional test report
`mushi connect`	Non-interactive: config + env (default) + Cursor MCP (default) + optional `--wait` heartbeat
`mushi login`	Save credentials to `~/.config/mushi/config.json` (mode `0o600`; legacy `~/.mushirc` auto-migrates)
`mushi setup`	Wire Cursor/Claude MCP from saved config — not SDK install (run `login` first)
`mushi whoami`	Verify API key and show project info
`mushi ping`	Backend connectivity probe
`mushi config`	View or update CLI config
`mushi upgrade`	Bump installed `@mushi-mushi/*` packages to latest stable
`mushi migrate`	Suggest migration guides based on `package.json`
`mushi project create`	Create project, mint key, write config
`mushi doctor`	Local + optional server preflight checks
`mushi nudge`	Print a phase-tuned `Mushi.init()` snippet (`alpha` / `beta` / `ga`)
`mushi reset <projectId> --confirm`	Archive project and wipe test data (irreversible)
`mushi completion <bash\|zsh\|fish>`	Print a tab-completion script generated from the live command tree

`mushi doctor`


mushi doctor                  # local: config, endpoint, SDK install
mushi doctor --server         # + 4 dispatch checks (GitHub, codebase, Anthropic, autofix)
mushi doctor --ingest         # + SDK heartbeat / first-report ingest steps
mushi doctor --host-app       # + host wiring: env vars, MCP config, hash-router capture
mushi doctor --qa-stories     # + QA story setup warnings (needs --server credentials)
mushi doctor --full           # run every check category in one pass
mushi doctor --json           # machine-readable; exits 1 if any check fails

--host-app (also included in --full) scans your source for hash-routed SPAs — HashRouter, createHashRouter, location.hash, hashchange — and, when it finds them, advises adding /#/-prefixed discoverInventory.routeTemplates to your Mushi.init() so parametric hash routes group in the Inventory instead of inflating it one row per slug. It’s advisory only (never fails the run) and stays silent when no hash routing is present. See Hash-routed SPAs.

`mushi nudge`

Generate a ready-to-paste Mushi.init() snippet tuned for your release phase (proactive triggers, cooldowns, feature-request card, beta-mode UI).


mushi nudge --phase beta              # default phase
mushi nudge --phase alpha --explain   # + human-readable summary of the preset
mushi nudge --phase ga --max 2 --cooldown 24 --dwell 5 --welcome 10

Flag	Meaning
`--phase <alpha\|beta\|ga>`	Release phase preset (default `beta`)
`--explain`	Print a human-readable summary of what the preset does
`--max <n>`	Override `maxProactivePerSession` (≥ 1)
`--cooldown <hours>`	Override `dismissCooldownHours` (≥ 0)
`--dwell <minutes>`	Override page-dwell threshold (`0` disables)
`--welcome <seconds>`	Override first-session welcome delay (`0` disables)

Reports & lessons


mushi reports list [--status new] [--severity critical]
mushi reports show <id>
mushi reports triage <id> --status acknowledged --severity high
mushi reports resolve <id>
mushi reports reopen <id>
mushi reports dismiss <id>
mushi reports reply <id> "Thanks — we're on it"
mushi reports search "checkout button"
 
mushi lessons list
mushi lessons show <id>
mushi sync-lessons              # pull promoted rules → .mushi/lessons.json

Agentic fixes

`mushi fix <reportId>`

Dispatch an agentic fix for a classified report.


# Default agent (from project settings)
mushi fix 00000000-0000-0000-0000-000000000123
 
# Cursor Cloud Agent — wait for PR
mushi fix <reportId> --agent cursor_cloud --wait
 
# CI: fail the pipeline if the fix errors
mushi fix $REPORT_ID --agent cursor_cloud --wait && echo "Fix PR opened"

Flag	Description
`--agent <name>`	`claude_code` (default), `cursor_cloud`, `codex`, `mcp`
`--model <slug>`	Model override for `cursor_cloud` (e.g. `composer-latest`)
`--no-auto-pr`	Skip automatic PR creation for `cursor_cloud`
`--wait`	Poll until terminal state; exits non-zero on failure

`mushi fixes`

Headless fix lifecycle — pairs with mushi fix --wait.


# Stream dispatch SSE events (no browser)
mushi fixes tail --report-id <reportId>
 
# Pull latest GitHub Actions status (same as console "Refresh CI status")
mushi fixes refresh-ci <fixId>
mushi fixes refresh-ci <fixId> --json
 
# Squash-merge the draft PR and mark the report Fixed
mushi fixes merge <fixId>
mushi fixes merge <fixId> --method squash   # default
mushi fixes merge <fixId> --method merge
mushi fixes merge <fixId> --json

Merge prerequisites: the fix attempt must be completed with an open PR (pr_url

pr_number). Draft PRs are auto-readied via GitHub GraphQL before merge (same as the console). Requires GitHub App or PAT connected and an API key with mcp:write.

When merge succeeds, the report moves to Fixed, the reporter gets notified, and fix.applied webhooks fire — identical to merging on GitHub or via the admin console.

QA coverage & TDD


# Live crawl → inventory proposal
mushi stories map --url https://your-app.com --wait
mushi stories map --url https://app.com --provider browserbase --cursor-refine
 
# TDD test generation
mushi tdd gen <storyId> --mode review
mushi tdd pending
mushi tdd approve <qaStoryId>
mushi tdd improve                    # PDCA on failing tests
mushi tdd run <qaStoryId>
 
# QA story ops
mushi qa stories
mushi qa runs <storyId>
mushi qa run <storyId>
mushi audit                        # full-stack project health audit

Skill pipelines


mushi skills list [--category workflow] [--search "fix bug"]
mushi skills show workflow-fix-and-ship
mushi skills sync [--source-id <id>]
 
mushi pipeline start <reportId> --skill workflow-fix-and-ship [--mode cloud]
mushi pipeline watch <runId-or-prefix>
mushi pipeline checkin <runId-or-prefix> --step 0 --status passed [--notes "Done"]

Mode	Behavior
`handoff`	Prints a context packet for your local Cursor agent
`cloud`	Dispatches each step to Cursor Cloud; status streams to the console

Integrations, keys & Slack


mushi integrations list
mushi integrations test slack
mushi integrations test sentry
mushi integrations test github
 
mushi keys list
MUSHI_BYOK_KEY=sk-ant-... mushi keys add --provider anthropic --label "Backup"
 
mushi slack status
mushi slack test

Indexing, sourcemaps & deploy


mushi index ./src                    # upload codebase chunks to RAG
mushi sourcemaps upload --release 1.4.2 --dir ./dist
mushi deploy check                   # edge-function health + latency
mushi test                           # synthetic report end-to-end

Environment variables

Variable	Purpose
`MUSHI_API_KEY`	Admin or ingest API key (prefer env over `--api-key` flag)
`MUSHI_API_ENDPOINT`	API base URL
`MUSHI_PROJECT_ID`	Project UUID
`MUSHI_CONSOLE_URL`	Admin console base for CLI hints + browser opens
`MUSHI_BYOK_KEY`	BYOK key value for `mushi keys add` (keeps key out of shell history)
`MUSHI_NO_UPDATE_CHECK=1`	Skip npm registry version nudge in `mushi init`

Config file: ~/.config/mushi/config.json (Unix mode 0o600; legacy ~/.mushirc auto-migrates on first load).

@mushi-mushi/cli