Reference

CLI reference.

Commands, flags, and settings for the matilda CLI.

Install and verify

Shell

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

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.

Shell

matilda

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.

Data

{
  "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.