# CLI overview

> Install the maru command, find its command groups, and use it from a terminal, a script, CI or a coding agent.

Canonical: https://maru.audio/docs/cli
Documentation index: https://maru.audio/llms.txt

`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:

```bash
npm i -g maruaudio
maru --version
```

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

```bash
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](https://maru.audio/docs/audio-sdk.md) 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:

```bash
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](https://maru.audio/docs/authentication.md) |
| `maru doctor` | Check what this machine can do | [Check this machine](#check-this-machine) |
| `maru init` | Create a module project | [Create a project](https://maru.audio/docs/create.md) |
| `maru dev` | Run the live development workbench | [Development workbench](https://maru.audio/docs/dev.md) |
| `maru module …` | Check, evaluate, preview, build, export and prepare a module release | [Check, build and export](https://maru.audio/docs/export.md) |
| `maru plugin …` | Build, inspect, install and remove native plugins | [Native plugins](https://maru.audio/docs/native-plugins.md) |
| `maru skill …`, `maru mcp …`, `maru guide …`, `maru tools …` | Connect coding agents | [Use Maru from your agent](https://maru.audio/docs/agent-setup.md), [Agents and MCP](https://maru.audio/docs/agents-and-mcp.md) |
| `maru project …`, `maru bank …`, `maru preset …` | Work with hosted Studio projects, banks and presets | [Hosted projects and banks](#hosted-projects-and-banks) |
| `maru resolve`, `maru install`, `maru render` | Look up, install and render published modules by reference | [Install and render](#install-and-render) |
| `maru hardware …` | Create a hardware project from a module | [From module to hardware](https://maru.audio/docs/from-module-to-hardware.md) |

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](https://maru.audio/docs/authentication.md)).

## Check this machine

```bash
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`](https://maru.audio/docs/authentication.md), you can create and inspect
hosted Studio projects and sound banks from the terminal:

```bash
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](https://maru.audio/docs/studio-workflow.md). `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:

```bash
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`:

```bash
eval "$(maru completion zsh)"
```

## Related

Start a project with [Create a project](https://maru.audio/docs/create.md), or let a coding agent
drive the CLI with [Agents and MCP](https://maru.audio/docs/agents-and-mcp.md).