CLI overview

maru is the command-line program for Maru. It creates module projects, runs the development workbench, checks, builds and exports modules, builds native plugins, signs you in to hosted services, and serves Maru's operations to coding agents. Studio, the CLI, MCP clients and the maruaudio library all run the same operations.

Install

The CLI ships in the maruaudio npm package. Install it globally:

npm i -g maruaudio
maru --version

Or run it without installing; npx maruaudio accepts every command maru does:

npx maruaudio --help

The package installs both maru and maruaudio as commands. A project can also add maruaudio as a dependency, which gives it the library imports described in the Audio SDK and a pinned CLI version for its scripts.

Use the CLI to create, develop, check and build modules. Install the compiler components and platform SDKs for your selected browser, native plug-in or hardware targets. maru doctor and maru module doctor report build readiness and missing prerequisites.

Find a command

The CLI describes itself. Start with help and follow it down:

maru --help              # command groups and top-level commands
maru module --help       # the commands in one group
maru module build --help # the arguments and options of one command

Commands	Purpose	Guide
maru login, whoami, logout	Sign in to hosted Maru services	Sign in
maru doctor	Check what this machine can do	Check this machine
maru init	Create a module project	Create a project
maru dev	Run the live development workbench	Development workbench
maru module …	Check, evaluate, preview, build, export and prepare a module release	Check, build and export
maru plugin …	Build, inspect, install and remove native plugins	Native plugins
maru skill …, maru mcp …, maru guide …, maru tools …	Connect coding agents	Use Maru from your agent, Agents and MCP
maru project …, maru bank …, maru preset …	Work with hosted Studio projects, banks and presets	Hosted projects and banks
maru resolve, maru install, maru render	Look up, install and render published modules by reference	Install and render
maru hardware …	Create a hardware project from a module	From module to hardware

Options are not repeated in these guides. --help always shows the options of the version you have installed, and maru tools describe prints the exact input schema of every operation.

Output for scripts

Add --json to any command to print its structured result on stdout instead of text. Errors go to stderr; with --json they are a JSON object with a code, the exit code, a message and, when there is one, a hint with the command that fixes the problem.

Exit codes are stable, so a script or agent can branch on them:

Code	Meaning
0	Success
1	The command ran and failed
2	Invalid usage or input; nothing ran
3	Not signed in, or the credentials were rejected
4	A prerequisite is missing, such as a component, an extension or a hosted service
5	The item's licence does not allow it, such as remixing a module its creator reserved
6	The item is for sale and you have not bought it yet

Input is validated before any file, network or build work starts, so a mistyped option exits with code 2 without side effects.

Prompts, CI and agents

In an interactive terminal, the CLI asks before a destructive operation. It never prompts when the CI environment variable is set, when stdin is not a terminal, or when an MCP client or agent is calling. In those cases:

• a destructive command needs --yes;
• a command with a missing prerequisite, such as a compiler component or SDK, fails with exit code 4 and reports what to install;
• a command that needs an account fails with exit code 3 unless a token is supplied, for example through MARU_TOKEN (see Sign in).

Check this machine

maru doctor

maru doctor reports your Node.js version, whether you are signed in, and the platform tools that native builds use, such as CMake and a C++ compiler. Missing items come with a suggested fix. It only reports and always exits with code 0, so it is safe to run anywhere, including CI. Run it first on a new machine, and paste its output when you report a problem.

To check one module project's build readiness rather than the whole machine, run maru module doctor in the project.

Hosted projects and banks

Signed in with maru login, you can create and inspect hosted Studio projects and sound banks from the terminal:

maru project templates             # starting points for a new project
maru project create <template>     # create a hosted project from one
maru project show                  # the project in the current scope
maru bank create "<title>"         # create a sound bank
maru preset list                   # presets saved to the current project

These are the same operations web Studio and its agent use, so a project created here opens in Studio. maru project --help, maru bank --help and maru preset --help list the full set.

Install and render

Published modules and sampler banks have a reference, @handle/slug, with an optional @version. The same reference works in the terminal and in the Maru plug-ins:

maru resolve @handle/slug                 # what it is and which Maru plug-in loads it
maru install @handle/slug                 # into the library the plug-ins read, for offline use
maru render @handle/slug --audio in.wav --out out.wav
maru render @handle/slug --midi riff.mid --out out.wav --offline

maru render plays an installed module offline and writes a 48 kHz, 32-bit float WAV, so a script can check that what it installed actually sounds. An instrument plays the notes of a MIDI file (--midi); an effect processes a 48 kHz WAV (--audio). --params sets parameter values before the first block, for example --params '{"master.level":0.5}'. A module that is not installed yet is installed first; with --offline nothing is downloaded and the command exits with code 4 if the module is not on this machine. Add --json for the WAV's checksum and its peak, RMS and clipping counts. Sampler banks cannot be rendered from the terminal yet; load them in Maru Sampler.

Shell completion

maru completion prints a completion script for bash, zsh or fish, generated from the same command tree as --help:

eval "$(maru completion zsh)"

Related

Start a project with Create a project, or let a coding agent drive the CLI with Agents and MCP.