Reference: command line

Neutral description of the mm executable: flags, positional argument, environment variables, start-up output and exit codes.

Invocation

mm [-config <path>] [-acp] [-tui] [--version] [--about] [<path>]

Element	Type	Default	Description
`-config <path>`	string	`""`	Path of the YAML configuration file.
`<path>`	positional	none	Same as `-config`, when `-config` is not given. A second positional argument is an error.
`-acp`	bool	`false`	Serve the Agent Client Protocol on stdin/stdout instead of the terminal REPL.
`-tui`	bool	`false`	Open the single-window mode (conversation above, input box below). Same effect as `tui: true` in the YAML; ignored with `-acp`. Falls back to the line mode when stdin or stdout is not a terminal.
`--version`	bool	`false`	Print the version and exit, before the configuration is read. `-version` is the same flag.
`--about`	bool	`false`	Print what `mm` is — one screen: version, the three front ends, the tools, the model servers, where the project and the docs live — and exit, before the configuration is read.
`-h`	—	—	Print the flag usage and exit.

Version

mm --version (or -version) prints one line and exits, before the configuration file is looked for — so it answers in any directory, with no model server running:

mm v0.0.3 (go1.26.5, darwin/arm64)

mm --about prints the same version inside a short description of the program. The version also opens the start-up banner (mm v0.0.3 | config: …), which the window mode keeps as the conversation's first line, and sits in the window's status bar before the counters.

Where it comes from	What you see
A release binary, stamped at build time by `02-build-releases.sh`	The tag: `v0.0.3`
`go install`ed from a tagged version	That tag
Built by hand from a working tree (`go build`, `./install.sh`)	The short commit, `9073268`, with `+dirty` when the tree had uncommitted changes
Built with `-buildvcs=false`	`unknown`

Configuration file resolution

The first existing source wins.

Order	Source	Missing file
1	`-config` flag or positional argument	Error, exit code 1
2	`AGENT_CONFIG` environment variable	Error, exit code 1
3	`./agent.yaml`	Not an error: built-in defaults are used, the banner shows `config: built-in defaults`

Environment variables

Variable	Effect
`AGENT_CONFIG`	Path of the configuration file (see above).
`AGENT_PROVIDER`	Overrides the `provider` key.
`AGENT_MODEL`	Overrides the `model` key.
`AGENT_BASE_URL`	Overrides `baseUrl` and disables the fallback probe.
`DMR_BASE_URL`	Same as `AGENT_BASE_URL`, for the `dmr` provider only; `AGENT_BASE_URL` wins when both are set.
Variable named by `apiKeyEnv`	Holds the API key. Default name: none for `dmr`, `LLAMA_API_KEY` for `llamacpp`.

Start-up output

Printed on stdout in terminal mode, on stderr in ACP mode. Dimmed when stdout is a terminal.

Line	Content
`[warning: …]`	Zero or more probe warnings: server unreachable, model not in the server's list, no chat template, compression that can never trigger, no tool declared at all.
`mm <version> \| config: … \| provider: … \| model: … \| ctx: … \| tools: … \| skills: N`	Version (see above), configuration path, provider name, model identifier, context window with its origin (`config`, `/props`) or `unknown`, declared tool names, number of skills found.
`Agent ready. Commands: …`	Terminal mode only.
`Shortcut: Ctrl+C …`	Terminal mode only.
`sessions: saved under <dir>[ · N earlier — /resume to continue the latest, /sessions to list]`	Terminal mode, `sessions.enabled` only: the resolved sessions directory and how many sessions it already holds.

Example

[warning: llamacpp: nothing answers at http://127.0.0.1:8080/v1 — start it: llama-server -m <model.gguf> --jinja --port 8080]
mm v0.0.3 | config: agent.llamacpp.yaml | provider: llamacpp | model: jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M | ctx: unknown | tools: bash, read_file, write_file, edit_file | skills: 0

ACP mode specifics

Aspect	Behaviour
stdout	JSON-RPC 2.0 messages only, one per line.
stderr	Banner, warnings, `[acp] …` trail, SDK logs.
Spinner	Disabled.
Relative `skillsDir`	Resolved relative to the directory of the configuration file, when a file was found; otherwise from the working directory, as in terminal mode.

Window mode specifics

Aspect	Behaviour
Selection	`-tui` flag, or `tui: true` in the YAML; `-acp` wins over both.
Terminal check	Both stdin and stdout must be character devices. Otherwise `[tui: stdin or stdout is not a terminal — running the line mode]` is printed and the line mode runs, banner included.
Screen	The terminal's alternate screen, released on exit; the terminal's own scrollback is not written to.
Banner	Not printed on stdout; shown as the first line of the conversation.
Spinner	Disabled; the rule under the conversation animates instead.
Model name	The header shows a short form of the model identifier: registry host and organisation dropped, the `-gguf` format suffix dropped, the tag kept, capped at 28 characters (`huggingface.co/unsloth/qwen3.5-2b-gguf:Q4_K_M` → `qwen3.5-2b:Q4_K_M`). The full identifier is in the start-up banner, which the window keeps as the conversation's first line.
Layout	Header line (agent, model `@` provider, context use as `ctx N% (used/window)` or `ctx ~used (window unknown)`, `session <id>` when sessions are on); conversation with a scroll bar; rule with state and key hints; 3-row input box; status bar (`F1 help · Ctrl-Y copy · F2 mouse: … · Ctrl-C quit` on the left, `<version> · N msgs · N tools` on the right — the version is dropped when the two sides would not fit, so the key hints are never truncated to make room for it).
Tool calls	`‣ <tool> <detail> <status> <time>` where status is `… pending`, `… waiting for permission`, `… running`, `✓ done` or `✗ failed`; output folded to `previewLines` lines (`… N more line(s)`); `+`/`-` lines of `write_file`/`edit_file` output coloured.
Pickers	`/` completes a command, `@` a path under the working directory, `$` a skill of the catalogue — the last two anywhere in a sentence, keeping their prefix. See Slash commands.
Thinking	A thinking model's reasoning is its own `‣ thinking` entry, dim italic in a different colour, before the answer. Hidden with `showThinking: false`.
Errors	One line `[error: <explanation>]`; a cancelled turn shows `🛑 Generation aborted.`; each turn ends with `⚙ N command(s) [· 📝 N file op(s)] [· 📖 N skill(s)]`.
Permissions	With `permissions: ask`, the box shows `? <tool title>` with `[a] allow once [s] allow <tool> for this session [r] reject` until answered; a turn cancelled while asking rejects.
Keys	See Slash commands — window keys.
Mouse	Not captured at start-up, so the terminal's click-and-drag selection works. `F2` captures it (wheel scrolling; `Shift`+drag selects) and releases it again.

Exit codes

Code	Cause
0	`/quit`, `Ctrl+C` at the prompt, end of stdin, or the ACP client closed the connection.
1	More than one positional argument; configuration load error; engine initialisation error (unknown provider, required key not set).

Build and install

Command	Effect
`go build -o mm .`	Builds the binary in the current directory.
`./install.sh`	Builds `mm` and copies it to `/usr/local/bin`, with `sudo` when the directory is not writable.
`go test ./...`	Runs the unit tests.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119


# Reference: command line

> Neutral description of the `mm` executable: flags, positional argument, environment variables, start-up output and exit codes.

## Invocation

```
mm [-config <path>] [-acp] [-tui] [--version] [--about] [<path>]
```

| Element | Type | Default | Description |
|---------|------|---------|-------------|
| `-config <path>` | string | `""` | Path of the YAML configuration file. |
| `<path>` | positional | none | Same as `-config`, when `-config` is not given. A second positional argument is an error. |
| `-acp` | bool | `false` | Serve the Agent Client Protocol on stdin/stdout instead of the terminal REPL. |
| `-tui` | bool | `false` | Open the single-window mode (conversation above, input box below). Same effect as `tui: true` in the YAML; ignored with `-acp`. Falls back to the line mode when stdin or stdout is not a terminal. |
| `--version` | bool | `false` | Print the version and exit, before the configuration is read. `-version` is the same flag. |
| `--about` | bool | `false` | Print what `mm` is — one screen: version, the three front ends, the tools, the model servers, where the project and the docs live — and exit, before the configuration is read. |
| `-h` | — | — | Print the flag usage and exit. |

## Version

`mm --version` (or `-version`) prints one line and exits, before the configuration file is looked for — so it answers in any directory, with no model server running:

```
mm v0.0.3 (go1.26.5, darwin/arm64)
```

`mm --about` prints the same version inside a short description of the program. The version also opens the start-up banner (`mm v0.0.3 | config: …`), which the window mode keeps as the conversation's first line, and sits in the window's status bar before the counters.

| Where it comes from | What you see |
|---|---|
| A release binary, stamped at build time by `02-build-releases.sh` | The tag: `v0.0.3` |
| `go install`ed from a tagged version | That tag |
| Built by hand from a working tree (`go build`, `./install.sh`) | The short commit, `9073268`, with `+dirty` when the tree had uncommitted changes |
| Built with `-buildvcs=false` | `unknown` |

## Configuration file resolution

The first existing source wins.

| Order | Source | Missing file |
|-------|--------|--------------|
| 1 | `-config` flag or positional argument | Error, exit code 1 |
| 2 | `AGENT_CONFIG` environment variable | Error, exit code 1 |
| 3 | `./agent.yaml` | Not an error: built-in defaults are used, the banner shows `config: built-in defaults` |

## Environment variables

| Variable | Effect |
|----------|--------|
| `AGENT_CONFIG` | Path of the configuration file (see above). |
| `AGENT_PROVIDER` | Overrides the `provider` key. |
| `AGENT_MODEL` | Overrides the `model` key. |
| `AGENT_BASE_URL` | Overrides `baseUrl` and disables the fallback probe. |
| `DMR_BASE_URL` | Same as `AGENT_BASE_URL`, for the `dmr` provider only; `AGENT_BASE_URL` wins when both are set. |
| Variable named by `apiKeyEnv` | Holds the API key. Default name: none for `dmr`, `LLAMA_API_KEY` for `llamacpp`. |

## Start-up output

Printed on stdout in terminal mode, on stderr in ACP mode. Dimmed when stdout is a terminal.

| Line | Content |
|------|---------|
| `[warning: …]` | Zero or more probe warnings: server unreachable, model not in the server's list, no chat template, compression that can never trigger, no tool declared at all. |
| `mm <version> \| config: … \| provider: … \| model: … \| ctx: … \| tools: … \| skills: N` | Version (see above), configuration path, provider name, model identifier, context window with its origin (`config`, `/props`) or `unknown`, declared tool names, number of skills found. |
| `Agent ready. Commands: …` | Terminal mode only. |
| `Shortcut: Ctrl+C …` | Terminal mode only. |
| `sessions: saved under <dir>[ · N earlier — /resume to continue the latest, /sessions to list]` | Terminal mode, `sessions.enabled` only: the resolved sessions directory and how many sessions it already holds. |

### Example

```
[warning: llamacpp: nothing answers at http://127.0.0.1:8080/v1 — start it: llama-server -m <model.gguf> --jinja --port 8080]
mm v0.0.3 | config: agent.llamacpp.yaml | provider: llamacpp | model: jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M | ctx: unknown | tools: bash, read_file, write_file, edit_file | skills: 0
```

## ACP mode specifics

| Aspect | Behaviour |
|--------|-----------|
| stdout | JSON-RPC 2.0 messages only, one per line. |
| stderr | Banner, warnings, `[acp] …` trail, SDK logs. |
| Spinner | Disabled. |
| Relative `skillsDir` | Resolved relative to the directory of the configuration file, when a file was found; otherwise from the working directory, as in terminal mode. |

## Window mode specifics

| Aspect | Behaviour |
|--------|-----------|
| Selection | `-tui` flag, or `tui: true` in the YAML; `-acp` wins over both. |
| Terminal check | Both stdin and stdout must be character devices. Otherwise `[tui: stdin or stdout is not a terminal — running the line mode]` is printed and the line mode runs, banner included. |
| Screen | The terminal's alternate screen, released on exit; the terminal's own scrollback is not written to. |
| Banner | Not printed on stdout; shown as the first line of the conversation. |
| Spinner | Disabled; the rule under the conversation animates instead. |
| Model name | The header shows a short form of the model identifier: registry host and organisation dropped, the `-gguf` format suffix dropped, the tag kept, capped at 28 characters (`huggingface.co/unsloth/qwen3.5-2b-gguf:Q4_K_M` → `qwen3.5-2b:Q4_K_M`). The full identifier is in the start-up banner, which the window keeps as the conversation's first line. |
| Layout | Header line (agent, model `@` provider, context use as `ctx N% (used/window)` or `ctx ~used (window unknown)`, `session <id>` when sessions are on); conversation with a scroll bar; rule with state and key hints; 3-row input box; status bar (`F1 help · Ctrl-Y copy · F2 mouse: … · Ctrl-C quit` on the left, `<version> · N msgs · N tools` on the right — the version is dropped when the two sides would not fit, so the key hints are never truncated to make room for it). |
| Tool calls | `‣ <tool>  <detail>  <status>  <time>` where status is `… pending`, `… waiting for permission`, `… running`, `✓ done` or `✗ failed`; output folded to `previewLines` lines (`… N more line(s)`); `+`/`-` lines of `write_file`/`edit_file` output coloured. |
| Pickers | `/` completes a command, `@` a path under the working directory, `$` a skill of the catalogue — the last two anywhere in a sentence, keeping their prefix. See [Slash commands](slash-commands.md#the-three-pickers). |
| Thinking | A thinking model's reasoning is its own `‣ thinking` entry, dim italic in a different colour, before the answer. Hidden with `showThinking: false`. |
| Errors | One line `[error: <explanation>]`; a cancelled turn shows `🛑 Generation aborted.`; each turn ends with `⚙ N command(s) [· 📝 N file op(s)] [· 📖 N skill(s)]`. |
| Permissions | With `permissions: ask`, the box shows `? <tool title>` with `[a] allow once   [s] allow <tool> for this session   [r] reject` until answered; a turn cancelled while asking rejects. |
| Keys | See [Slash commands — window keys](slash-commands.md#window-mode-keys). |
| Mouse | Not captured at start-up, so the terminal's click-and-drag selection works. `F2` captures it (wheel scrolling; `Shift`+drag selects) and releases it again. |

## Exit codes

| Code | Cause |
|------|-------|
| 0 | `/quit`, `Ctrl+C` at the prompt, end of stdin, or the ACP client closed the connection. |
| 1 | More than one positional argument; configuration load error; engine initialisation error (unknown provider, required key not set). |

## Build and install

| Command | Effect |
|---------|--------|
| `go build -o mm .` | Builds the binary in the current directory. |
| `./install.sh` | Builds `mm` and copies it to `/usr/local/bin`, with `sudo` when the directory is not writable. |
| `go test ./...` | Runs the unit tests. |