# CLI reference

> Commands, flags, and settings for the matilda CLI.

Source: https://maincode.com/docs/cli-reference
Section: Matilda Code · Matilda documentation

---

## Install and verify

```bash
npm install -g @maincode-ai/matilda-code@latest
matilda --version
```

The package installs `matilda` and `matilda-code`. They are the same binary.

## Commands

Running `matilda` with no subcommand starts an interactive session in the
current directory. Anything else you type as a positional argument is treated
as a prompt.

| Field | Type | Description |
| - | - | - |
| `matilda` | `command` | Start an interactive session, or run a positional prompt one-shot. |
| `auth` | `command` | Sign in, sign out, or check status. Subcommands: login, logout, status (alias whoami). |
| `sessions` | `command` | List and manage recorded sessions. |
| `mcp` | `command` | Manage MCP servers available to the agent. |
| `extensions` | `command` | Install and manage Matilda extensions. |
| `hooks` | `command` | Manage hooks. Also available as /hooks in a session. |
| `channel` | `command` | Manage messaging channels such as Telegram and Discord. |
| `serve` | `command` | Run Matilda as a local HTTP daemon. Experimental. |
| `update` | `command` | Update Matilda Code in place. |

> **Note** — There is no `matilda run` or `matilda diff`. To run a single task, pass the
> prompt directly. To see pending changes, use `/diff` inside a session.

## Commands you will actually use

**matilda**

Start an interactive session in the current directory. The agent reads the
working tree, waits for a task, and pauses for approval before it writes or
runs anything.

```bash
matilda
```

**matilda auth**

Sign in once per machine. The token lands in `~/.matilda/matilda-auth.json`
with user-only permissions.

```bash
matilda auth login
matilda auth status
matilda auth logout
```

**One-shot prompt**

Run a single task and exit, for scripts and CI. Combine with `-o json` when
something downstream has to parse it.

```bash
matilda "add a --json flag to the export command"
matilda -p "list every TODO in src/" -o json
```

**matilda sessions**

Sessions are recorded per project. List them, then resume the one you want.

```bash
matilda sessions
```

Use `--continue` or `--resume` on a new run to pick up where you left off.
`--fresh` starts a clean one-shot that neither resumes nor records.

## Global flags

These apply to any invocation:

| Field | Type | Description |
| - | - | - |
| `--model, -m` | `string` | Model for this invocation. |
| `--prompt, -p` | `string` | Run one prompt non-interactively. Ambient piped stdin is ignored when set. |
| `--prompt-interactive, -i` | `string` | Run a prompt, then stay in the interactive session. |
| `--output-format, -o` | `text \| json \| stream-json` | Shape of the CLI output. Defaults to text. |
| `--approval-mode` | `plan \| default \| auto-edit \| auto \| yolo` | How much the agent may do without asking. |
| `--bogan, --yolo, -b` | `boolean` | Auto-approve every action. Shorthand for the yolo mode. |
| `--sandbox, -s` | `boolean` | Run tool calls inside the sandbox. |
| `--include-directories, --add-dir` | `array` | Additional directories to include in the workspace. |
| `--allowed-tools` | `array` | Tools that bypass confirmation for this run. |
| `--mcp-config` | `string` | MCP server config as inline JSON or a path to a JSON file. |
| `--fresh, --no-resume` | `boolean` | Start a fresh one-shot session without resuming or recording history. |
| `--debug, -d` | `boolean` | Run in debug mode. |

## Slash commands

Inside a session, `/help` lists everything. The ones worth knowing early:

| Field | Type | Description |
| - | - | - |
| `/help` | `command` | List every slash command. |
| `/auth` | `command` | Switch account, API token, or provider. |
| `/model` | `command` | Pick the model for this session. |
| `/approval-mode` | `command` | Change what the agent may do without asking. |
| `/context` | `command` | Show what is loaded and how much of the window it uses. |
| `/compress` | `command` | Summarise the conversation to free up context. |
| `/clear` | `command` | Drop the working set and start fresh. |
| `/diff` | `command` | Show pending changes. |
| `/memory` | `command` | Inspect and edit what Matilda remembers. |
| `/init` | `command` | Create a MATILDA.md for this project. |
| `/mcp` | `command` | Inspect connected MCP servers. |
| `/doctor` | `command` | Diagnose a broken setup. |
| `/aussie` | `command` | Hop a Matilda easter egg across the terminal. Takes an optional animal. |

> **Note** — `/aussie` takes `kangaroo`, `koala`, `wombat`, `emu`, or `quokka`, and picks
> one at random if you leave it off. Interactive sessions only, and `Esc` clears
> it early.

## Settings

Settings are JSON, not TOML, and they layer. Later layers win:

| Field | Type | Description |
| - | - | - |
| `~/.matilda/settings.json` | `user` | Applies to every session for this user. |
| `.matilda/settings.json` | `project` | Applies only in this repository. Overrides user settings. |
| `System settings` | `system` | Machine-wide, for administrators. Overrides user and project. Path varies by OS. |

Environment variables override the files, and command-line flags override
everything.

```json title=".matilda/settings.json"
{
  "tools": {
    "approvalMode": "default"
  }
}
```

> **Note** — String values in `settings.json` can reference environment variables with
> `$VAR_NAME` or `${VAR_NAME}`, so credentials never have to be written into the
> file itself.

## Environment

| Field | Type | Description |
| - | - | - |
| `MATILDA_API_KEY` | `string` | Matilda API token for CI and other non-interactive runs. Not needed for interactive use. |