musher-cli

A small command-line client for the Cloud Musher board API. It lets a person — or an AI agent running headless — drive the board (tickets, docs & decisions, workspaces) from the terminal by talking to the REST API with a personal access token (PAT). The CLI acts as that user and inherits their role (viewer / editor / admin), so RBAC is enforced server-side.

This is a local operator tool. It is never deployed to a server.

Requirements

• Node.js ≥ 20 (uses the global fetch)

Install / build

npm install
npm run build      # tsc → dist/
node dist/index.js --help

Optionally link it so musher is on your PATH:

npm link           # then: musher --help

Authentication — folder-local .env

The CLI's identity and workspace come from the folder you stand in. Each workspace folder carries its own ./.env; one shared musher binary aliases to whichever folder you run it from. There is no ambient global identity.

Tokens are created in the web Settings panel (not the CLI). Once you have a msh_… PAT, scaffold the folder:

musher init                        # prompts for API URL, token, workspace → writes ./.env (0600)
musher init --url http://localhost:3001 --token msh_xxx --workspace musher
musher init --force                # overwrite an existing ./.env

init validates the token against /api/auth/me before writing, refuses to clobber an existing ./.env without --force, and writes mode 0600. Copy .env.example by hand if you prefer.

./.env holds three keys:

MUSHER_API_URL=http://localhost:3001
MUSHER_TOKEN=msh_…
MUSHER_WORKSPACE=musher            # workspace slug (recommended) or id

musher login also writes ./.env (URL + token, preserving any workspace); musher logout clears the token from ./.env. Neither writes ~/.musher/config.json anymore.

The nearest .env is auto-loaded at startup — the CLI searches the current directory then walks up to the first .env it finds, so subfolders inherit their parent workspace folder's context. Real environment variables always win over .env file values.

Run a command from a folder with no .env and no token and you get:

No .env or MUSHER_TOKEN in this folder — run 'musher init' here.

Precedence

| What | Order (first wins) | | --- | --- | | workspace | --workspace flag → real MUSHER_WORKSPACE env → .env file → (error) | | token | real MUSHER_TOKEN env → .env file → deprecated ~/.musher/config.json (warns) | | apiUrl | real MUSHER_API_URL env → .env file → deprecated global config (warns) → http://localhost:3001 |

Every workspace-scoped command (tickets ls/new, docs ls/new/get/edit/accept/reject/supersede) defaults its workspace from this chain, so no --workspace flag is needed inside a configured folder:

cd my-workspace && musher tickets ls          # scoped to MUSHER_WORKSPACE from ./.env
MUSHER_TOKEN=msh_xxx MUSHER_WORKSPACE=musher musher tickets ls --json   # env-only, for CI

Workspace id vs slug: the CLI forwards whatever you set (id or slug). The API resolves slugs everywhere; a workspace id (UUID) currently works only on some read paths (RBAC + a few ?workspace= filters) — the ticket list filter and the create handlers are slug-only. Use the slug (e.g. musher) for reliable end-to-end behavior today.

Deprecated: ~/.musher/config.json is now a read-only fallback and emits a one-line deprecation warning when used. It is scheduled for removal next release — migrate to ./.env via musher init.

Commands

Every read command accepts --json for raw, agent-friendly output.

| Command | Description | | --- | --- | | musher init [--url] [--token] [--workspace] [--force] | Scaffold ./.env for this folder | | musher login [--url] [--token] | Authenticate → writes ./.env | | musher logout | Clear the token from ./.env | | musher whoami [--json] | Show the authenticated user | | musher tickets ls [--workspace <slug>] [--lane <lane>] [--json] | List tickets | | musher tickets get <id> [--json] | Show a ticket incl. body | | musher tickets new --title <t> [--workspace <slug>] [--type] [--prio] [--epic] [--agents a,b] [--body <md>] [--json] | Create a ticket | | musher tickets edit <id> [--title] [--prio] [--type] [--epic] [--agents] [--body] | Edit provided fields | | musher tickets move <id> <lane> [--evidence <text>] | Transition a ticket | | musher tickets rm <id> [--yes] | Delete a ticket (admin) | | musher tickets comment <id> <body…> | Add a comment | | musher tickets comments <id> [--json] | List comments | | musher docs ls [--workspace <slug>] [--kind <kind>] [--json] | List documents (filter by --kind decision) | | musher docs get <ref> [--workspace <slug>] [--json] | Show a document/decision (by ref, id, or path) | | musher docs new --title <t> [--group <g>] [--kind <kind>] [--workspace <slug>] [--body <md>] | Create a document (or a decision with --kind decision) | | musher docs edit <id> [--title] [--group] [--workspace] [--body] | Edit provided fields | | musher docs accept <ref> [--workspace <slug>] | Accept a decision → active (admin) | | musher docs reject <ref> [--workspace <slug>] | Reject a decision → deprecated (admin) | | musher docs supersede <ref> --by <ref2> [--workspace <slug>] | Supersede a decision (admin) | | musher workspaces ls [--json] | List workspaces | | musher users ls [--json] | List users |

Global: musher --version, musher --help, musher <group> --help.

Errors

Failures print a friendly message and exit non-zero:

• no token in folder → No .env or MUSHER_TOKEN in this folder — run 'musher init' here.
• 401 → Not authenticated. Run \musher init` here (or set MUSHER_TOKEN).`
• 403 → Permission denied — your role (<role>) can't do that.
• network error → Can't reach the Musher API at <url>. Is it running?

.env holds a real PAT — it is gitignored (only .env.example is committed) and written mode 0600. Never commit or print it.