Musher Commands

Complete command reference for the musher CLI.

Authentication

Authenticate with the Musher platform using your API key.

bash

musher auth login

Prompts for your API key interactively. The credential is stored in your OS keyring (or a fallback file). See Configuration for storage details.

musher auth logout

Clear stored credentials from your machine.

bash

musher auth logout

musher auth status

Display your authenticated identity and writable namespaces.

bash

musher auth status

Output

User:       [email protected]
Namespaces: acme (owner), acme-labs (member)

Consumer Commands

Top-level shortcuts for discovering and using bundles. These are the primary commands for bundle consumers.

musher search

Search the Musher Hub for bundles. Opens an interactive TUI with live search results. In non-interactive mode, falls back to batch output.

bash

musher search [query]

Flag	Description
`--type <type>`	Filter by asset type (e.g. `skill`, `agent`)
`--sort <field>`	Sort results

Example

musher search "code review"

musher load

Load a bundle from the registry and prepare it for use with a harness. Opens an interactive TUI to preview the bundle and select a harness. In non-interactive mode, falls back to batch output.

bash

musher load <namespace>/<slug>[:<version>]

Flag	Description
`--force`	Re-download even if already cached
`--no-tui`	Disable TUI mode (use batch output)

Example

musher load acme/code-review
musher load acme/code-review:1.0.0

musher run

Load a bundle and run it with a harness in one step. Downloads the bundle (if not cached), materializes assets into the harness's directory layout, launches the harness, and cleans up injected files when the session ends.

bash

musher run <namespace>/<slug>[:<version>]

Flag	Description
`--harness <name>`	Target harness (e.g. `claude`, `cursor`)
`--project-dir <path>`	Project directory to run in
`--force`	Re-download even if already cached

Example

musher run acme/code-review --harness claude
musher run acme/code-review:1.0.0 --harness cursor

Bundle Authoring

Commands for creating and publishing bundles. These are under the musher bundle subcommand group.

musher bundle init

Scaffold a new bundle project in the current directory. Creates musher.yaml, skill templates, and a README.

bash

musher bundle init

Flag	Description
`--namespace <name>`	Pre-fill the namespace field
`--slug <name>`	Pre-fill the bundle slug
`--empty`	Create `musher.yaml` only, without scaffolding templates

Example

musher bundle init --namespace acme --slug code-review-kit

musher bundle add

bash

musher bundle add [path...]

Flag	Description
`--all`	Discover and register all conventional assets in the project

Example

# Add specific files
musher bundle add skills/code-review/SKILL.md agents/review/AGENT.yaml

# Auto-discover all conventional assets
musher bundle add --all

musher bundle remove

Remove asset entries from your musher.yaml bundle definition.

bash

musher bundle remove <asset-id>

Flag	Description
`--all`	Remove all registered assets

Example

musher bundle remove my-old-skill

musher bundle validate

Validate the bundle definition and verify that all referenced source files exist.

bash

musher bundle validate

Output

✓ musher.yaml is valid
✓ 3 assets found
✓ All source files exist
✓ Bundle is ready to push

Flag	Description
`--file <path>`	Path to `musher.yaml` (default: current directory)

musher bundle push

Validate the bundle and push an immutable version to the registry.

bash

musher bundle push

Output

✓ Bundle validated
✓ Pushed acme/code-review-kit:1.0.0
  OCI ref: registry.musher.dev/acme/code-review-kit:1.0.0

Flag	Description
`--file <path>`	Path to `musher.yaml` (default: current directory)
`--dry-run`	Validate and show what would be pushed without actually pushing
`--publish-to-hub`	Also create or update the public Hub listing after pushing

musher bundle pull

Download a bundle from the registry to your local cache. Use --output-dir to extract flat files to a specific directory.

bash

musher bundle pull <namespace>/<slug>[:<version>]

Flag	Description
`-o <dir>`	Extract bundle contents to a directory
`--force`	Re-download even if already cached
`--json`	Output structured JSON with bundle metadata and file paths

Example

musher bundle pull acme/code-review-kit:1.0.0 -o ./bundles

musher bundle load

Download a bundle and prepare it for use with a harness (non-interactive). This is the batch equivalent of the interactive musher load command.

bash

musher bundle load <namespace>/<slug>[:<version>]

Flag	Description
`--harness <name>`	Target harness (e.g. `claude`)
`--force`	Re-download even if already cached

Example

musher bundle load acme/code-review --harness claude

musher bundle yank

Soft-withdraw a published version from resolution. Yanked versions won't be returned by resolve queries but remain visible in detail views for audit purposes.

bash

musher bundle yank <namespace>/<slug>:<version>

Flag	Description
`--reason <text>`	Record why the version was yanked (recommended)

Example

musher bundle yank acme/code-review-kit:1.0.0

musher bundle unyank

Restore a previously yanked version, making it available for resolution again.

bash

musher bundle unyank <namespace>/<slug>:<version>

Example

musher bundle unyank acme/code-review-kit:1.0.0

Hub

Manage public listings on Musher Hub. The Hub is the public discovery layer — you can push bundles to the registry without listing them on the Hub.

musher hub search

Search for bundles on the Hub (non-interactive). Omit the query to see recently updated bundles. For interactive search, use musher search instead.

bash

musher hub search [query]

Example

musher hub search code-review

musher hub info

Show detailed information about a bundle listing, including available versions.

bash

musher hub info <namespace>/<slug>

Example

musher hub info acme/code-review-kit

musher hub list

List all bundles published under a namespace.

bash

musher hub list <namespace>

Example

musher hub list acme

musher hub categories

List available Hub categories for bundle listings.

bash

musher hub categories

musher hub publish

Create or update a public Hub listing for a bundle. Requires description, readme, and license or licenseFile in your musher.yaml.

bash

musher hub publish <namespace>/<slug>

Example

musher hub publish acme/code-review-kit

musher hub deprecate

Mark a bundle listing as deprecated on the Hub.

bash

musher hub deprecate <namespace>/<slug>

musher hub undeprecate

Remove the deprecation marker from a bundle listing.

bash

musher hub undeprecate <namespace>/<slug>

Configuration

musher config get

Get a configuration value.

bash

musher config get <key>

Example

musher config get api_url

musher config set

Set a configuration value.

bash

musher config set <key> <value>

Example

musher config set api_url https://api.musher.dev

musher config list

List all configuration values.

bash

musher config list

Cache

Manage the local bundle cache.

musher cache info

Show cache location and size.

bash

musher cache info

musher cache list

List cached bundles.

bash

musher cache list

musher cache clean

Remove all cached bundles.

bash

musher cache clean

musher cache prune

Remove stale or unused entries from the cache.

bash

musher cache prune

Maintenance

musher doctor

Run diagnostic checks on your environment — verifies authentication, registry connectivity, and CLI configuration.

bash

musher doctor

Output

✓ CLI version: 0.4.2
✓ Authenticated as [email protected]
✓ Registry reachable: registry.musher.dev
✓ Keyring available

musher update

Update the musher CLI to the latest version.

bash

musher update

musher version

Display the installed CLI version and build information.

bash

musher version

Output

musher 0.4.2
commit: a1b2c3d
built:  2026-03-15T10:30:00Z

musher completion

Generate shell completion scripts for your terminal.

bash

# Add to ~/.bashrc
eval "$(musher completion bash)"

bash

# Add to ~/.zshrc
eval "$(musher completion zsh)"

bash

musher completion fish | source

Global Flags

These flags are available on all commands:

Flag	Description
`--api-url <url>`	Override the default API endpoint
`--api-key <key>`	Supply credentials directly (prefer `MUSHER_API_KEY` env var)
`--json`	Output in JSON format
`--quiet`	Minimal output for automation
`--no-color`	Disable colored output
`--no-input`	Disable interactive prompts
`--no-tui`	Disable TUI mode (use batch output)