Command reference

Every npm script, the headless CLI, smoke/maintenance scripts, and environment variables. Source of truth: package.json. Setup from source: setup-from-source.md. System map: architecture.md and ../context.md.

For UI key bindings (composer, editor, file tree, terminal), see Keyboard shortcuts.

Running & building

Generated artifacts

prebuild runs these automatically before npm run build; run them by hand when you change a source of truth and want the generated file refreshed without a full build.

Headless CLI (minnow run)

For an external agent connection, run node bin/minnow.mjs mcp as a stdio MCP server. Minnow must already be running. See MCP hub setup for client configuration and HTTP transport.

Drives one agent turn without the SPA. Requires the tool server (npm start) or pass --start-server. Entry: bin/minnow.mjs → src/headless/cli-main.ts. An installed build has no minnow command; it carries a bundled copy of this entry that only the Scheduler runs.

minnow run --workspace . --agent builder --mode build \
  --prompt "Summarize README.md" --json-out run.json

# or via npm
npm run minnow:run -- --prompt "Reply OK" --json

Flags (minnow run --help for the authoritative list):

Use --provider minnow-library --model "mtplx:<repo-id>" for an MTPLX row in My Models (or its gguf: / mlx: library ID). The server reuses or loads the model with its saved engine preference. Explicit CLI choices override work-agent defaults; unavailable models and unknown providers fail clearly. Scheduler runs use the same binding behavior.

UI-only tools (e.g. ask_question) fail with a clear error in headless mode unless you opt into unsafe automation (MINNOW_I_UNDERSTAND_UNSAFE_AUTOMATION).

Account chat latency benchmark

node scripts/benchmark-chat-latency.mjs --account --samples 3 --output /tmp/chat-latency.json runs synthetic cold/warm replies and a tool round through installed CLI adapters and configured API providers. --account explicitly enables billable inference using existing logins/keys. Override targets with --targets '[{"providerId":"codex-cli","model":"gpt-6-luna","kind":"codex"},{"providerId":"opencode-go","model":"gpt-6-luna"}]'; omit kind for API targets and use "claude" for Claude Code or "cursor" for Cursor Agent. --restart adds a CLI follow-up after closing its process to measure checkpoint recovery. The script uses a temporary workspace, cleans its native sessions, records failed targets, and does not save chats. Measurements end at the local generation subscriber, before browser paint. Compare distributions across runs: native instructions, account routing and upstream load differ even for the same model.

Opt-in MTPLX lifecycle audit

With a running scratch MINNOW_HOME host and an unused installed model/port:

node scripts/audit-mtplx-lifecycle.mjs \
  --base-url http://127.0.0.1:19473 --home /tmp/minnow-audit-home \
  --library-id "mtplx:Publisher/Model" --port 19488 \
  --output /tmp/mtplx-lifecycle.json

This performs real inference, kills its verified owned daemon to check restart, and tests direct-client traffic across idle windows. It rejects the live profile and existing serves, preserves external daemons, stops its own processes in finally, and writes a result manifest without credentials. It requires installed MTPLX weights and takes about two minutes; it is separate from npm test.

Backup and restore CLI (minnow backup, minnow restore)

The same engine as Settings → General → Backup and restore, run directly against the Minnow home. No server is needed, and it is plain Node — no tsx. Entry: bin/minnow.mjs → server/backup/cli.js. User-facing behaviour is in the manual: Backup and restore.

# Encrypted, with credentials; the passphrase comes from the environment, never argv
MINNOW_BACKUP_PASSPHRASE='…' minnow backup --out /mnt/backups --passphrase-env MINNOW_BACKUP_PASSPHRASE

# What would be backed up, with sizes
minnow backup --list

# Preview a backup (changes nothing), then restore it
minnow restore /mnt/backups
minnow restore /mnt/backups --yes --passphrase-env MINNOW_BACKUP_PASSPHRASE

• minnow backup uses the category selection saved in backup.json unless --include is given. Without --passphrase-env the backup is unencrypted and leaves credentials out, and the command says so.
• minnow restore without --yes only prints the preview. With --yes it stages the backup; if no Minnow host has the home open (see run/host.json, written by server/runtime/host-lock.js) it applies at once, otherwise at the next start.
• Set MINNOW_HOME to restore into a different profile.
• Exit codes: 0 success, 1 failure (message on stderr), 2 usage.

Tests

npm test runs the full suite via test/run-all.mjs — it discovers every test/**/*.test.{js,mjs,mts,ts} file and runs the correct runner/loader per path (see test/test-config.mjs). New test files are included automatically; npm run test:check-coverage fails CI when a file would be orphaned. Worker parallelism defaults to min(16, availableParallelism()); override with MINNOW_TEST_CONCURRENCY.

Memory: every runner preloads test/assert-dom-safe.mjs. Without it a failing assert.equal(document.querySelector('.x'), null) hands a happy-dom node to node:assert, which inspects it at depth: 1000 and Myers-diffs the result — synchronous, unbounded typed-array allocation that --max-old-space-size cannot cap, and enough to freeze a 64 GB workstation from a single test process (measured: one child at 49 GB and still climbing). The guard compares DOM operands itself and reports a short descriptor (<section.board-root>) instead. Do not remove the preload, and prefer assert.ok(!el) over comparing elements when adding assertions.

CI (MIN-383): .github/workflows/ci.yml runs on pull requests and pushes to main: npm ci → test:check-coverage → npx tsc --noEmit → npm test on windows-latest, ubuntu-latest, and macos-latest (includes test/headless/). Require the ci status check on main before merge (.github/BRANCH_PROTECTION.md).

Scoped suites (each delegates to node test/run-all.mjs --suite <name>):

Most TS/UI suites run under tsx with --import ./test/test-loader.mjs (stubs .css + xterm); some use --experimental-test-module-mocks.

Skill maintenance

Orchestrate board dev tools

Smoke scripts

Run with the server up (default port 9473 — substitute yours). API calls need the per-boot session token from ~/.minnow/session-token:

npx tsx scripts/sa16-smoke.mjs http://localhost:9473       # general/sub-agent smoke
node test/terminal-stream.test.mjs http://localhost:9473   # terminal stream API
npx tsx scripts/step16-memory-smoke.mjs http://localhost:9473

Other scripts/*.mjs cover stepwise feature smokes, Electron launch, token/CSS generation, and migrations — see the scripts/ folder.

Environment variables