How to Install and Use Muse Code CLI (2026 Setup Guide)

Meta released Muse Code in beta on August 5, 2026. This is the practical setup guide: install, authenticate, configure, run it safely, and wire it into CI.

Every command below was verified against Meta's published documentation and the shipped 0.1.0-R708.1 binary. Where something is not documented, this guide says so rather than inventing it — which matters more than usual here, because several early guides published commands and file paths that do not exist.

What do you need before installing?

Very little. The installer hard-checks exactly two commands — curl and mktemp — and runs under bash.

• No Node.js, Python or Homebrew. The binary is statically linked.
• git is not needed to install, but is required at runtime for the worktree features.
• Platforms: macOS and Linux, on x86_64 or arm64.

Native Windows is not supported. The installer hard-fails with unsupported platform. Windows users should install inside WSL2.

How do you install Muse Code?

The one-liner:

curl -fsSL https://dev.meta.ai/install.sh | bash

Check the domain. Several published guides print dev.ai/install.sh. That is a different site and does not serve the installer. The correct host is dev.meta.ai.

If your team does not pipe remote scripts into a shell — a reasonable policy — download and read it first:

curl -fsSL https://dev.meta.ai/install.sh -o install.sh
less install.sh
bash install.sh

The installer places a self-updating launcher at ~/.local/bin/muse and downloads the real binary alongside it as ~/.local/bin/muse-bin-<version>. It appends this line to your shell profile:

export PATH="$HOME/.local/bin:$PATH" # added by muse installer

Restart your shell, then confirm:

muse --version
# Muse Code 0.1.0 (0.1.0-R708.1)

Installer options

Four environment variables control the install:

A tidy install that leaves your dotfiles alone:

MUSE_NO_MODIFY_PATH=1 MUSE_INSTALL_DIR="$HOME/bin" bash install.sh

Note that Muse Code auto-updates hourly by default. On a build machine or anywhere you need reproducibility, set MUSE_NO_AUTO_UPDATE=1.

How do you authenticate?

Run:

muse login

This is an OAuth 2.0 device-code flow — it prints a code and a verification URL that you approve in a browser. Because it is device-code rather than a localhost callback, it works fine over SSH, contrary to launch coverage implying a desktop-only browser flow.

The credential is stored at ~/.config/muse/auth.json (or $XDG_CONFIG_HOME/muse/auth.json). It is not ~/.muse/ — several guides get this wrong.

To sign out:

muse logout

That clears the stored browser session and any stored key, but does not unset a META_API_KEY you exported — remove that separately.

API keys for scripts and CI

Two supported routes. The environment variable is the CI path:

export META_API_KEY="your-key-here"

META_API_KEY always takes priority over an account login. If an environment key is hiding a browser session, Muse Code tells you at startup.

To store a key on disk without it ever appearing in your shell history or process list:

printf '%s' "$META_API_KEY" | muse auth set --api-key-stdin

The binary refuses secrets passed as flag values outright, which is a good design choice. Meta Managed Account users cannot use browser sign-in at all and must use an API key.

You need a payment method before it will run

Worth knowing before you start, because it stops people at the first step: installing and authenticating is not enough. The download is around 97 MB, and on first run the agent refuses to work until a payment method is attached to your account. There is no free tier and, as of this launch, no starter credit — the $20 credit offered at the earlier Muse Spark 1.1 launch is gone. Without a card you hit a 402 paywall.

Muse Code is genuinely low-cost. It is not free. Add a payment method at the Meta developer billing page before you plan a first session, and note that only team admins can do this on a team account.

Access itself may also be a hurdle depending on where you are: many developers outside the US report that the cheaper contributor model id returns Model not found, and that VPNs generally do not work around it. Meta has not published a regional restriction, so treat that as widely user-reported rather than confirmed — but do not build a budget on contributor pricing until you have confirmed you can actually call it.

How do you start your first session?

cd /path/to/your/project
muse

On first entry Muse Code asks whether to trust the workspace. Trusting it loads that project's skills, rules and hooks, and the choice is remembered per workspace root.

You can also pass a prompt directly:

muse "fix the failing test in src/parse.ts"

Seed your project rules

muse init            # writes AGENTS.md
muse init --dry-run  # show what it would write, write nothing
muse init --force    # overwrite an existing AGENTS.md

This writes a single AGENTS.md and nothing else. On a real repository, the in-session /init command inspects up to a dozen files — manifests, READMEs, representative source and tests — and fills in the project layout and common commands from actual evidence.

There is no MUSE.md. Meta adopted the cross-vendor AGENTS.md convention and falls back to reading CLAUDE.md, so existing project rules largely carry over.

Bring your existing skills across

muse skills import --from claude
muse skills import --from codex

These look in ~/.claude/skills and ~/.codex/skills. Muse Code also scans repo-local .claude/skills and .codex/skills directories automatically.

What are the essential commands?

The top-level subcommands:

Inside a session, the slash commands you will reach for most:

• /help and /keymap — full command list and shortcuts
• /effort — set reasoning effort: none, minimal, low, medium, high (default), xhigh, ultra
• /usage — session usage and cost. Check this early and often
• /compact — summarise history to reclaim context room
• /subagents and /tasks — view running children and background tasks
• /stop — stop all background tasks
• /goal — start or manage continuous work toward an objective (pause, resume, clear)
• /fork — branch a new session from the current one
• /side — a short parallel conversation that leaves the main thread untouched
• /rules — show which markdown files govern this session

While a turn is running you are not locked out: Enter injects a steer into the turn in progress, Alt+Enter queues text for the next turn, and Esc interrupts. Note that Esc stops the turn only — background terminals and subagents keep going until /stop.

A correction on the built-in skills

Launch coverage widely described /plan and /grill as slash commands. They are not — they are skills, invoked as /skill plan or /skill grill. /goal is a genuine slash command. The real built-in skill ids are create-skill, doctor, git, grill, grill-and-record, import, manage-settings, plan, read-session and taste.

How do you configure Muse Code?

User settings live at ~/.config/muse/settings.json. One rule dominates: the file must contain "schema_version": 1. Omit it and every command fails at startup with malformed settings file.

The file holds model defaults, terminal UI preferences, tool and MCP server configuration, a hooks block, a runtime_capabilities map, and telemetry options. A missing file is fine — Muse Code applies defaults — so only create one when you actually have something to set.

Other paths worth knowing:

• ~/.config/muse/auth.json — credentials
• ~/.config/muse/trust.json — workspace trust decisions
• ~/.local/share/muse/ — session logs
• .muse/ in your repo — the append-only event log and retained worktrees

Turn down the token burn

Muse Code runs four background observer agents — memory recall, skill recall, goal tracking and verification. The first three are on by default and each makes its own model calls, adding token usage on top of your main session. If your bill looks higher than expected, toggle them in the runtime_capabilities block of your settings file.

There is no .museignore. The only ignore file Muse Code respects is .gitignore. To scope the agent to a subdirectory, use --workspace <PATH>.

How do you run it safely?

Approval and sandboxing are on by default — a genuinely good posture that you should mostly leave alone.

Approval modes, set with --approval-mode:

• on-request (default) — commands run unless they match the dangerous set: rm -f, rm -rf, or sudo in front of either
• untrusted — anything without a matching allow rule stops for review
• never — nothing stops; the sandbox alone contains what runs

For a genuinely paranoid first run on an unfamiliar repo, a read-only audit mode:

muse --approval-mode untrusted --disable-write --disable-shell

The sandbox uses Seatbelt on macOS and a bundled bubblewrap helper on Linux. Your workspace and a temp directory are writable; everything else is read-only, and .git, .muse and .agents stay read-only even inside the workspace. Network defaults to proxy-only, adjustable with --sandbox-network restricted|enabled|proxy-only. The sandbox fails closed — if it cannot enforce the boundary, it will not run.

muse --yolo disables approval and the sandbox together and trusts the workspace for that run. Use it only in a disposable, already-isolated environment such as a CI container. It is not a convenience flag for your laptop.

How do you run Muse Code in CI?

muse exec runs one prompt to completion with no UI. A working recipe:

export META_API_KEY="$MUSE_KEY"

muse exec --json --yolo \
  --max-model-steps 40 \
  --reasoning-effort medium \
  --prompt-file ./task.md

The flags that matter in a pipeline:

• --json — machine-readable JSONL events on stdout
• --max-model-steps <N> — hard cap on model steps. Your main cost control, since there is no spend cap
• --max-tool-output-bytes <N> — cap tool output fed back to the model
• --prompt-file <PATH> — read the prompt from a file (cannot be combined with an inline prompt)
• --disable-web-tools — no web access for the run
• --session-id <UUID> — pin a session id for later inspection

For parallel work, -w create puts the session in its own git worktree based on HEAD. Subagent concurrency scales to your core count minus two, clamped between 2 and 16.

Common problems in the first 48 hours

"unsupported platform"

You are on native Windows, or an unsupported architecture. Use WSL2.

"malformed settings file"

Your ~/.config/muse/settings.json is missing "schema_version": 1. Add it. An unrecognised value fails differently, with unsupported settings schema version.

muse: command not found

The installer appended ~/.local/bin to your shell profile but your current shell has not reloaded. Restart it or source your rc file. If you used MUSE_NO_MODIFY_PATH=1, add the directory yourself.

The sandbox refuses to start

It fails closed by design. Run muse sandbox to check the setup. On Linux this usually means the bundled bubblewrap helper cannot get the permissions it needs — common in containers without the right capabilities.

Flag validation errors

The worktree flags are strict and interdependent: --worktree-base requires --worktree create, --worktree-existing requires --worktree existing, and --worktree requires session logging, so it cannot be combined with --no-session-log.

There is no muse doctor

Diagnostics live in a skill, not a subcommand. Run /skill doctor inside a session.

Watch your bill before you scale up

Muse Code has no subscription and no spend cap. Usage billing accrues and charges at a payment threshold or on the first of the month.

The standard tier is $1.25 per million input tokens and $4.25 output. The contributor tier is $0.10 and $0.20 — but Meta trains on your inputs and outputs, and throttles you to 60 requests per minute against standard's 3,000. Do not point the contributor tier at proprietary code, and do not let the tier be chosen by whoever is trying to reduce the AI bill. See what the contributor tier actually costs you.

Use /usage during sessions and --max-model-steps in automation. Those are your only real guardrails.

FAQ

How do I install Muse Code?

Run curl -fsSL https://dev.meta.ai/install.sh | bash on macOS or Linux, restart your shell, then confirm with muse --version. The domain is dev.meta.ai — guides printing dev.ai are wrong.

Does Muse Code need Node.js or Python?

No. The binary is statically linked. The installer needs only curl, mktemp and bash. git is required at runtime for worktree features.

Where does Muse Code store its credentials?

At ~/.config/muse/auth.json, or $XDG_CONFIG_HOME/muse/auth.json if set. Not ~/.muse/.

Can I install Muse Code on Windows?

Not natively — the installer hard-fails. Use WSL2.

How do I use Muse Code in CI?

Set META_API_KEY from your secret store and run muse exec --json --prompt-file ./task.md. Add --max-model-steps to cap cost, and only use --yolo inside a disposable container.

How do I stop Muse Code auto-updating?

Set MUSE_NO_AUTO_UPDATE=1. It otherwise checks hourly, which you probably do not want on a build machine.

Is there a .museignore file?

No. Muse Code respects .gitignore only. Use --workspace <PATH> to scope it to a subdirectory.

Why is my token usage higher than expected?

Three of the four background observer agents run by default and each makes its own model calls on top of your session. Toggle them in the runtime_capabilities block of ~/.config/muse/settings.json.

How do I migrate my Claude Code setup?

Run muse skills import --from claude. Muse Code reads AGENTS.md, falls back to CLAUDE.md, and scans repo-local .claude/skills automatically.