`@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 --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 the CLI config file: `~/.config/mushi/config.json`, or `%APPDATA%\mushi\config.json` on Windows (full order; 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                  # config, endpoint, SDK install, ingest and dispatch readiness
mushi doctor --no-server      # skip the 4 dispatch checks (GitHub, codebase, Anthropic, autofix)
mushi doctor --no-ingest      # skip the SDK heartbeat / first-report checks
mushi doctor --host-app       # + host wiring: env vars, MCP config, hash-router capture
mushi doctor --qa-stories     # + QA story setup warnings (needs a signed-in CLI)
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

Sentry issues already open

The Sentry webhook only sees new issues. mushi sentry import brings in the ones already open, so they get the same diagnosis. Running it twice is safe: an issue already imported links to its report.


mushi sentry import                                  # newest unresolved issues
mushi sentry import WEB-1A2 WEB-1A3                  # by id or short id (up to 10)
mushi sentry import --query "level:error" --since-days 7
mushi sentry import --query "level:error" --cursor <next>   # next page, printed after each import

It needs the Sentry org slug, project slug and an auth token with event:read and project:read (console: Integrations → Sentry).

Reporter updates held for review

When reporter updates are in review mode, each status message waits in the outbox until you send it. Sending and discarding reach a real person, so both need --yes.


mushi outbox list
mushi outbox edit <messageId> "Fixed in 1.4, thanks for the report"
mushi outbox release <messageId> --yes
mushi outbox release <messageId> --text "Fixed in 1.4" --yes
mushi outbox discard <messageId> --yes

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
 
# A project with a frontend and a backend repo: send the fix to the backend
mushi fix <reportId> --repo acme/app-backend
 
# 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
`--repo <repoId\|owner/name>`	Linked repo to open the fix PR against, for a project with several repos. Defaults to the primary repo. A name is looked up among the project’s linked repos

`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

UX pass over every screen

mushi ux runs @mushi-mushi/ux on your machine. It maps every page, tab and dialog of your running app, then hands one screen at a time to the coding agent you choose, in a separate git worktree. An edit is kept only if accessibility, layout and console measurements don’t get worse. Exploring the app never sends a write request.


mushi ux ui                                              # studio: pick agent, model and skill; start; watch every attempt
mushi ux models --agent cursor                           # the models your account can use
mushi ux skills                                          # skill names from kensaurus/skills
mushi ux discover --url http://localhost:5173            # list the screens; edits nothing
mushi ux login --url http://localhost:5173               # sign in once, by hand, for signed-in screens
mushi ux run --dev "pnpm dev --port {port}" --agent claude-code
mushi ux run --dev "pnpm dev --port {port}" --agent cursor --model <id> --skill enhance-mobile-native-feel --base origin/main
mushi ux run --dev "pnpm dev --port {port}" --agent cursor-cloud --model grok-4.7   # edits run in Cursor Cloud
mushi ux open <runId>                                    # dashboard for a past run

The run ends with a branch, mushi-ux/<runId>, for you to review and open as a draft PR. Nothing is merged.

With --steps (on by default in mushi ux ui), the agent first plans each screen as 2–5 small, separate improvements without editing, then makes one per attempt; each step is measured and kept or rolled back on its own, so one bad step never costs the rest.

A run that stops for any reason (Stop, a closed terminal, a killed process) can be resumed with Resume in mushi ux ui, or with mushi ux run --resume <runId>: it carries on from the first unfinished screen with the settings it started with.

A run first checks, in about a minute, that the agent can read a file, and tells you what to fix if it cannot (--no-preflight skips it). On Windows, start the Cursor agent from PowerShell or cmd: the Cursor CLI also runs your Claude Code hooks, which can fail under Git Bash. Pass --ignore <selector> (repeatable) for elements that are not your app’s UI, such as a dev badge; dev overlays, build stamps and the Mushi widget are skipped already.

To run it on your repo’s GitHub Actions instead, add the mushi-ux.yml workflow and use Run in the cloud on the console’s UX runs page. It uses cursor-cloud and opens one draft PR.

Gate findings

mushi audit findings lists each finding from the recent gate runs with its file and line. mushi audit explain says why one fired, what it prevents and how to fix it. --gate takes any gate name: one this CLI version does not list is still sent to the server, with a warning.


mushi audit findings
mushi audit findings --gate code_health --severity error
mushi audit findings --all                      # include allowlisted findings
mushi audit explain <findingId>

Code health

Oversized files and bundle size that your CI posts to POST /v1/ingest/metrics.


mushi code-health show [--days 30]
mushi code-health stats

Your repo

These read the GitHub repo connected to the project. Mushi reads it through the GitHub connection and does not clone it.


mushi repo digest > digest.txt                  # one token-budgeted text for an LLM; summary goes to stderr
mushi repo digest --report <reportId>           # start from the files in that report's stack trace and fixes
mushi repo digest --path src/auth --budget 40000 --out digest.txt
 
mushi repo diagram show                         # the architecture diagram as an outline
mushi repo diagram generate [--force]           # draw it for the latest commit
mushi repo diagram publish --yes                # make it a public page (owners and admins)
mushi repo diagram unpublish --yes

publish shows where the page will go before it publishes. It sends the hash of exactly what the preview showed, so a diagram that changed in between is refused. A private repo can only be published from the console.

Releases

Release notes that credit the people who reported each fix and tell them it shipped.


mushi releases draft 1.4.0 [--since 2026-09-01]  # notes from the fixes merged in the window; nothing is sent
mushi releases list [--status draft]
mushi releases show <releaseId>
mushi releases edit <releaseId> --body-file notes.md
mushi releases publish <releaseId> --yes         # resolves the fixed reports and messages each credited reporter
mushi releases delete <releaseId> --yes          # drafts only
mushi releases stats

Spend limits


mushi budgets show                              # monthly AI budget, auto-fix caps, plan spend cap, auto-fix on/off
mushi budgets autofix off                       # fixes you start yourself always run
mushi billing cap 100                           # the plan's hard monthly cap

The monthly AI budget and the auto-fix caps are changed in the console (Settings → General → Spend limits), because that setting takes a signed-in session, not an API key.

App recipe


mushi recipe init                    # write a starter mushi.recipe.json from what the repo shows
mushi recipe check                   # validate it and its token files; run Mushi's deviance rules and print the 0–100 score
mushi recipe check --max-score 30    # also fail when the score is above 30
mushi recipe check --push            # send the recipe and the scan from your existing CI job; fails above the project's limit when that gate is on
mushi recipe show                    # each part of the recipe and its state

For --push, give CI a mushi login key (it carries mcp:read). A push with the SDK key (report:write only) keeps its findings and the CI gate, but never sets the score the console shows or dispatches a design fix, because that key ships inside your app.

Hole checks (radar)

Checks that catch a problem before a user hits it. scan runs in your own CI job; Mushi never clones your repo.


mushi radar scan                     # storage deletes done in SQL, secret keys in the built app; lists the build files the store rules read
mushi radar scan --push              # send results to Mushi (one extra step in your existing CI job, after the build step)
mushi radar scan --bundle-dir web/dist   # scan only these built client folders (repeatable), e.g. to leave out a server dist
mushi radar show                     # every hole check for this project and what it found

Run scan after your build step: it also reads the built app (dist, build, out, .next/static, .output/public, .svelte-kit/output/client, .vercel/output/static, native JS bundles) for secret keys. A dist that holds server code counts too; name the client folders with --bundle-dir to leave it out. With no build output, that check is left out and reads “Not checked”, never a pass. Only the file, the line and the kind of key are sent, never the key itself. The Supabase anon key and the Mushi SDK key are public by design and are not flagged.

One CI step for both checks

radar scan --push and recipe check --push belong in a job you already run, so they cost no extra job. Both need @mushi-mushi/cli 0.29.0 or later; an older CLI answers “unknown command”, and the packaged action stops with that version in its error instead. Store a project key as a repo secret first. The SDK ingest key works; an account-level (org) key does not. Both commands read the checked-out repo, so the job needs actions/checkout before them, and radar scan also reads the built app, so put the step after your build.

Copy-paste run: step, for any CI system:


- name: Mushi checks
  run: |
    npx --yes @mushi-mushi/cli@latest radar scan --push
    npx --yes @mushi-mushi/cli@latest recipe check --push
  env:
    MUSHI_API_KEY: ${{ secrets.MUSHI_INGEST_KEY }}

Packaged GitHub Action, the same CLI with the inputs spelled out:


- uses: actions/checkout@v4
- uses: kensaurus/mushi-mushi/packages/cli@master
  with:
    api-key: ${{ secrets.MUSHI_INGEST_KEY }}
    upload-sourcemaps: 'false'   # set 'true' (the default) to also upload source maps
    radar-scan: 'true'
    recipe-check: 'true'
    # working-directory: apps/web   # if the app is not at the repo root
    # fail-on-error: 'false'        # warn instead of failing the job

Input	Default	What it does
`radar-scan`	`false`	Runs `mushi radar scan --push`. Findings do not fail the job; they show on the hole checks.
`recipe-check`	`false`	Runs `mushi recipe check --push`. An invalid `mushi.recipe.json` (or none) fails the step.
`fail-on-error`	`true`	`false` turns a failed check or an unreachable Mushi into a warning.
`working-directory`	`.`	The repo root both checks read.
`upload-sourcemaps`	`true`	The action’s original source-map upload. Uses `release`, `sourcemaps-dir`, `dry-run`.

Run it on pushes to your default branch. recipe check --push records the commit SHA and branch from GITHUB_SHA and GITHUB_REF_NAME, and on a pull request the branch is the merge ref.

Store listings

Copy the live App Store and Google Play listings into the repo once, so the listing lives as code. It runs with your own keys and sends nothing to Mushi. Your own CI publishes listing changes after that.


mushi store pull --asc-key-id <id> --asc-issuer-id <id> --asc-key-path AuthKey.p8 \
  --play-key-path play-service-account.json

It reads store.listingDir, store.ios.appleId and store.android.package from mushi.recipe.json. The keys can also come from MUSHI_ASC_KEY_ID, MUSHI_ASC_ISSUER_ID, MUSHI_ASC_KEY_PATH and GOOGLE_APPLICATION_CREDENTIALS. Review the files before you commit them.

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

Several apps

For a team with more than one app. These read team-wide data, so they need an account-level key (console: Connect → MCP → account key), not a key bound to one project. If you belong to several teams, the error lists each one with the --org <id> to pass.


mushi portfolio show                 # each app: health, open reports, holes, SDK version, last release
mushi portfolio findings             # the same problem repeated across apps, SDK skew, integration holes
mushi portfolio resources            # domains, accounts and buckets shared between apps
mushi connectors list                # connectors with status and last error (read-only)
mushi connectors status <id>
mushi connectors actions             # requested connector actions and whether they ran
mushi funnel show                    # one funnel, every app side by side
mushi funnel set --steps signup,first_report,fix_merged --window 7d
mushi releases calendar              # what is waiting to ship in each app, and one suggested batch

Adding, probing or editing a connector takes credentials, so it stays in the console.

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`
`MUSHI_ASC_KEY_ID`, `MUSHI_ASC_ISSUER_ID`, `MUSHI_ASC_KEY_PATH`	Your App Store Connect key for `mushi store pull` (read on your machine, never sent to Mushi)

Config file

The CLI keeps credentials in one config.json. The first match wins:

$XDG_CONFIG_HOME/mushi/config.json when XDG_CONFIG_HOME is set, on any platform
%APPDATA%\mushi\config.json on Windows
~/.config/mushi/config.json otherwise (macOS, Linux)

On macOS and Linux the file is mode 0o600; on Windows the CLI restricts its ACL to your account (and SYSTEM) instead. A legacy ~/.mushirc auto-migrates on first load. mushi setup --help prints the path it resolved on your machine.

@mushi-mushi/cli