MinuteWork CLI

MinuteWork CLI for initializing a workspace, authenticating against a MinuteWork platform, linking a repo to a tenant-scoped public-site property, launching developer-local session broker flows, running local preview/test loops, submitting hosted preview deploys, and publishing app packs to the marketplace through the publication-review gate.

The npm package and primary command are minutework. The pandawork command remains available only as a compatibility alias for older installs and scripts.

External alpha scope

The current external alpha is intentionally narrow:

• Starters: tenant-app (combined public/private web surface), vuilder-app plus vuilder-shell (Vuilder public site plus branded customer shell), sidecar (local/internal runtime surface), and mobile (init-only native client)
• Developer-local broker surface: minutework session start|resume|status
• Hosted release class: ssr_container
• Deploy surface: minutework deploy --preview
• Capability gap queue: minutework gaps submit|status sends sanitized generated-workspace gap reports to platform BuilderCapabilityRequest records; GitHub Issue/PR promotion is server-side follow-up automation
• Deferred: --live, additional local coding engines, sidecar/runtime-backed deploys, and the commercial marketplace listing/pricing layer
• Marketplace publish: minutework publish submits the compiled, digest-bound app pack through the platform publication-review + attestation gate and publishes it to the public marketplace catalog only on an approved (or approved-with-warnings) attestation; a rejected attestation prints the review findings and exits 1 without publishing

The shipped tenant-app starter is the combined web surface: public routes at the root plus a private /app workspace. Public-site content follows the MinuteWork-managed mw.core.site baseline and published-snapshot flow.

For Vuilder verticals, scaffold vuilder-app and vuilder-shell together. vuilder-app is the public landing/blog/onboarding site; vuilder-shell is the branded customer tenant shell opened after central SSO and platform-owned customer_vertical_signup completion. Browser intake never chooses package refs, manifest refs, runtime provider, billing policy, or provisioning kind.

The CLI fails closed when the backend cannot provide typed release metadata, deploy status, receipts, activation state, or rollback state. It does not claim a successful deploy when the provider substrate is unavailable.

Install

npx minutework --help
npx minutework --version

For repeat use in a local environment:

npm install --global minutework@alpha

The package currently ships on a 0.x alpha channel. Publish from this repo with the manual GitHub Actions workflow at .github/workflows/minutework-cli-alpha-publish.yml.

External alpha paths

Start with the shared setup:

npx minutework init my-site --starter tenant-app
cd my-site
npx minutework login
npx minutework link

After link, the current alpha has two supported lanes (both tenant-app).

For a native mobile client, scaffold the mobile starter instead:

npx minutework init my-app --starter mobile

It is init-only and bring-your-own-UI: a minimal Expo (React Native) client that authenticates directly against the platform with a native device-flow session token (PKCE authorize -> exchange -> bearer + refresh in the device keychain), not the tenant-app BFF cookie path. There is no link/deploy lane for it — distribution is your own EAS pipeline (eas build/eas submit, EAS Update), not minutework deploy.

For a first-class Vuilder workspace, scaffold both web starters:

npx minutework init fleet-template --starter vuilder-app --starter vuilder-shell

The Vuilder public site redirects onboarding into central SSO. The approved app-pack marketplace coordinate is emitted by minutework publish and consumed by the platform customer-signup intent; the Vuilder shell customizes tenant UX, not platform identity/provisioning authority.

Developer-local broker lane

Use this lane when you want MinuteWork to assemble a bounded workspace context, persist broker state locally, and either prepare a human-mode session or launch the first supported local coding engine.

minutework session start --mode human
minutework session start --mode ai --engine claude
minutework session status
minutework session resume

• human and ai are alternative start modes, not a required sequence.
• Claude is the only supported local coding engine today.
• AI mode launches Claude with explicit workspace MCP bootstrap plus a bounded MinuteWork context pack instead of relying on implicit shell state.
• MinuteWork now installs and updates managed Claude Code automatically under the machine-local CLI state root when AI mode needs it, and prefers that managed Claude binary over any claude already on PATH.
• Claude authentication still happens outside MinuteWork. If Claude needs local login or account approval, complete that in Claude itself and rerun the MinuteWork session command.
• Current-session coordination stays repo-local under .minutework/, while preferences, per-session context packs, transcripts, and session history stay machine-local under the MinuteWork CLI state root.
• The broker fails closed on live overlap, missing engine binaries, stale session records, interrupts, and launch failures instead of allowing overlapping phantom sessions.
• Generated workspaces receive a root CLAUDE.md and AGENTS.md (rendered from the same source so they cannot drift) plus exported skills/ guidance tailored to the combined web, mobile, published-site, runtime-agent, OSS-adoption, and ontology workflows. Claude Code reads CLAUDE.md; Codex and other IDE agents read AGENTS.md.
• Generated guidance tells Claude/Codex/Cursor to record capability gaps as sanitized JSON first, submit likely reusable gaps with minutework gaps submit, and avoid direct GitHub Issue/PR workflows from the generated workspace.
• Broad project questions route through a project-orientation fast path so the agent can answer "what is this project about?" or "can we make an existing product agentic?" without the user naming individual skills.
• The workspace MCP (read-only context tools) is wired for Cursor (.cursor/mcp.json) and Codex (.codex/config.toml, which Codex loads for trusted projects); mcp/claude-desktop.sample.json is included for Claude Desktop.
• Managed guidance and MCP wiring can be refreshed later with minutework workspace sync-assets.
• Runtime-only Claude hooks are not exported into the generated workspace.

Local preview and deploy lane

Use this lane when you want the workspace-local preview/test loop or a hosted preview deploy:

minutework dev
minutework test
minutework deploy --preview

Combined tenant-app + sidecar workspaces keep sidecar setup explicit. Root pnpm install stays Node-only and does not run poetry install for you. If you need the sidecar, run pnpm run install:sidecar from the workspace root or cd sidecar && poetry install yourself before minutework dev or minutework test. Sidecar-only scaffolds have no root package.json; install Python deps once inside sidecar/ before running local sidecar workflows.

For direct third-party web hosts such as Vercel, deploy tenant-app only. In Vercel, point the project Root Directory at tenant-app; the optional sidecar remains a separate Poetry-managed surface.

link provisions or resolves the default published-site property for the active tenant and stores that property key in repo-local state. The SDK-based tenant-app/.env.example contains only the app metadata contract used by the template: NEXT_PUBLIC_MW_APP_ID, MW_TEMPLATE_APP_NAME, and optional MW_PUBLIC_BASE_URL. Browser auth and manifest calls use same-origin /_mw routes through @minutework/web-auth; do not add platform content tokens or public-site property vars to the tenant app.

deploy --preview always revalidates and recompiles before submit, prints a local-vs-remote diff, requires confirmation unless --yes is passed, polls typed receipts until a terminal state, and persists the last known preview deploy state under .minutework/deploy/preview/status.json. This alpha is preview-first; live public delivery remains follow-on.

Machine-readable output (--json)

validate, compile, codegen, deploy --preview, publish, and gaps accept --json so an IDE coding agent can drive them unattended and parse one stable shape. With --json the command prints a single result envelope to stdout and nothing else:

{
  "cliJsonVersion": 1,
  "command": "validate | compile | codegen | deploy | publish | gaps",
  "ok": true,
  "status": "ok | compiled | generated | activated | failed | rolled_back | confirmation_required | not_implemented | error",
  "result": {},
  "error": null
}

• ok mirrors the process exit code: 0 when ok is true, non-zero otherwise (fail-closed).
• result is the typed payload — the validate report (validate), the compile graph (compile / codegen), the terminal deploy receipt (deploy), publish review status (publish), or platform capability request status (gaps).
• deploy --preview --json runs unattended and never prompts. Pair it with --yes to authorize the deploy; without --yes it returns status: "confirmation_required" (exit 1) instead of blocking on a prompt.
• In --json mode the automatic diagnostic report is suppressed — the envelope and exit code are the whole contract.

Bug reporting

CLI failures automatically send a sanitized diagnostic report to the MinuteWork platform unless MW_CLI_BUG_REPORTS=never is set.

• Machine-readable verbs run with --json suppress automatic reporting; rely on the result envelope and exit code instead.

• Automatic reports never include raw .env contents, tokens, source files, or full local paths.

• The CLI keeps a local report bundle under the MinuteWork state root so you can retry or inspect what was sent.

• Use minutework report-bug --note "what happened" for manual reports.

• Use minutework report-bug --last --note "extra context" to resend the last saved bundle with more detail.

Requirements

• Node.js 18 or newer
• Poetry on PATH when your workspace includes the FastAPI sidecar and you plan to run it locally (then run pnpm run install:sidecar or cd sidecar && poetry install)
• A MinuteWork platform that exposes developer CLI auth, public-site preview deploy, and developer Builder capability-request endpoints
• An auth profile with interactive developer access, or a deploy token that includes deploy.preview.request

If the hosted preview provider is not configured, preview deploy returns a typed failure or rollback-preserved receipt instead of a fake success.

More docs

• Alpha onboarding: EXTERNAL_ALPHA.md
• Package smoke harness: scripts/starter-smoke.mjs