CLI

The Matrix CLI by default starts the TUI when run without any arguments.

matrix

But it also accepts commands as documented on this page. This allows you to interact with Matrix programmatically.

matrix run "Explain how closures work in JavaScript"

---

tui

Start the Matrix terminal user interface.

matrix [project]

Flags

Flag	Short	Description
--continue	-c	Continue the last session
--session	-s	Session ID to continue
--fork		Fork the session when continuing (use with --continue or --session)
--prompt		Prompt to use
--model	-m	Model to use in the form of provider/model
--agent		Agent to use
--port		Port to listen on
--hostname		Hostname to listen on

---

Commands

The Matrix CLI also has the following commands.

---

agent

Manage agents for Matrix.

matrix agent [command]

---

attach

Attach a terminal to an already running Matrix backend server started via serve or web commands.

matrix attach [url]

This allows using the TUI with a remote Matrix backend. For example:

# Start the backend server for web/mobile access
matrix web --port 4096 --hostname 0.0.0.0

# In another terminal, attach the TUI to the running backend
matrix attach http://10.20.30.40:4096

Flags

Flag	Short	Description
--dir		Working directory to start TUI in
--session	-s	Session ID to continue

---

create

Create a new agent with custom configuration.

matrix agent create

This command will guide you through creating a new agent with a custom system prompt and tool configuration.

---

list

List all available agents.

matrix agent list

---

auth

Command to manage credentials and login for providers.

matrix auth [command]

---

login

Matrix is powered by the provider list at Models.dev, so you can use matrix auth login to configure API keys for any provider you’d like to use. This is stored in ~/.local/share/matrix/auth.json.

matrix auth login

When Matrix starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a .env file in your project.

---

list

Lists all the authenticated providers as stored in the credentials file.

matrix auth list

Or the short version.

matrix auth ls

---

logout

Logs you out of a provider by clearing it from the credentials file.

matrix auth logout

---

github

Manage the GitHub agent for repository automation.

matrix github [command]

---

install

Install the GitHub agent in your repository.

matrix github install

This sets up the necessary GitHub Actions workflow and guides you through the configuration process. Learn more.

---

run

Run the GitHub agent. This is typically used in GitHub Actions.

matrix github run

Flags

Flag	Description
--event	GitHub mock event to run the agent for
--token	GitHub personal access token

---

mcp

Manage Model Context Protocol servers.

matrix mcp [command]

---

add

Add an MCP server to your configuration.

matrix mcp add

This command will guide you through adding either a local or remote MCP server.

---

list

List all configured MCP servers and their connection status.

matrix mcp list

Or use the short version.

matrix mcp ls

---

auth

Authenticate with an OAuth-enabled MCP server.

matrix mcp auth [name]

If you don’t provide a server name, you’ll be prompted to select from available OAuth-capable servers.

You can also list OAuth-capable servers and their authentication status.

matrix mcp auth list

Or use the short version.

matrix mcp auth ls

---

logout

Remove OAuth credentials for an MCP server.

matrix mcp logout [name]

---

debug

Debug OAuth connection issues for an MCP server.

matrix mcp debug <name>

---

models

List all available models from configured providers.

matrix models [provider]

This command displays all models available across your configured providers in the format provider/model.

This is useful for figuring out the exact model name to use in your config.

You can optionally pass a provider ID to filter models by that provider.

matrix models anthropic

Flags

Flag	Description
--refresh	Refresh the models cache from models.dev
--verbose	Use more verbose model output (includes metadata like costs)

Use the --refresh flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in Matrix.

matrix models --refresh

---

run

Run matrix in non-interactive mode by passing a prompt directly.

matrix run [message..]

This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.

matrix run Explain the use of context in Go

You can also attach to a running matrix serve instance to avoid MCP server cold boot times on every run:

# Start a headless server in one terminal
matrix serve

# In another terminal, run commands that attach to it
matrix run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flags

Flag	Short	Description
--command		The command to run, use message for args
--continue	-c	Continue the last session
--session	-s	Session ID to continue
--fork		Fork the session when continuing (use with --continue or --session)
--share		Share the session
--model	-m	Model to use in the form of provider/model
--agent		Agent to use
--file	-f	File(s) to attach to message
--format		Format: default (formatted) or json (raw JSON events)
--title		Title for the session (uses truncated prompt if no value provided)
--attach		Attach to a running matrix server (e.g., http://localhost:4096)
--port		Port for the local server (defaults to random port)

---

serve

Start a headless Matrix server for API access. Check out the server docs for the full HTTP interface.

matrix serve

This starts an HTTP server that provides API access to matrix functionality without the TUI interface. Set MATRIX_SERVER_PASSWORD to enable HTTP basic auth (username defaults to matrix).

Flags

Flag	Description
--port	Port to listen on
--hostname	Hostname to listen on
--mdns	Enable mDNS discovery
--cors	Additional browser origin(s) to allow CORS

---

session

Manage Matrix sessions.

matrix session [command]

---

list

List all Matrix sessions.

matrix session list

Flags

Flag	Short	Description
--max-count	-n	Limit to N most recent sessions
--format		Output format: table or json (table)

---

stats

Show token usage and cost statistics for your Matrix sessions.

matrix stats

Flags

Flag	Description
--days	Show stats for the last N days (all time)
--tools	Number of tools to show (all)
--models	Show model usage breakdown (hidden by default). Pass a number to show top N
--project	Filter by project (all projects, empty string: current project)

---

export

Export session data as JSON.

matrix export [sessionID]

If you don’t provide a session ID, you’ll be prompted to select from available sessions.

---

import

Import session data from a JSON file or Matrix share URL.

matrix import <file>

You can import from a local file or an Matrix share URL.

matrix import session.json
matrix import https://opncd.ai/s/abc123

---

web

Start a headless Matrix server with a web interface.

matrix web

This starts an HTTP server and opens a web browser to access Matrix through a web interface. Set MATRIX_SERVER_PASSWORD to enable HTTP basic auth (username defaults to matrix).

Flags

Flag	Description
--port	Port to listen on
--hostname	Hostname to listen on
--mdns	Enable mDNS discovery
--cors	Additional browser origin(s) to allow CORS

---

acp

Start an ACP (Agent Client Protocol) server.

matrix acp

This command starts an ACP server that communicates via stdin/stdout using nd-JSON.

Flags

Flag	Description
--cwd	Working directory
--port	Port to listen on
--hostname	Hostname to listen on

---

uninstall

Uninstall Matrix and remove all related files.

matrix uninstall

Flags

Flag	Short	Description
--keep-config	-c	Keep configuration files
--keep-data	-d	Keep session data and snapshots
--dry-run		Show what would be removed without removing
--force	-f	Skip confirmation prompts

---

upgrade

Updates matrix to the latest version or a specific version.

matrix upgrade [target]

To upgrade to the latest version.

matrix upgrade

To upgrade to a specific version.

matrix upgrade v0.1.48

Flags

Flag	Short	Description
--method	-m	The installation method that was used; curl, npm, pnpm, bun, brew

---

Global Flags

The matrix CLI takes the following global flags.

Flag	Short	Description
--help	-h	Display help
--version	-v	Print version number
--print-logs		Print logs to stderr
--log-level		Log level (DEBUG, INFO, WARN, ERROR)

---

Environment variables

Matrix can be configured using environment variables.

Variable	Type	Description
MATRIX_AUTO_SHARE	boolean	Automatically share sessions
MATRIX_GIT_BASH_PATH	string	Path to Git Bash executable on Windows
MATRIX_CONFIG	string	Path to config file
MATRIX_TUI_CONFIG	string	Path to TUI config file
MATRIX_CONFIG_DIR	string	Path to config directory
MATRIX_CONFIG_CONTENT	string	Inline json config content
MATRIX_DISABLE_AUTOUPDATE	boolean	Disable automatic update checks
MATRIX_DISABLE_PRUNE	boolean	Disable pruning of old data
MATRIX_DISABLE_TERMINAL_TITLE	boolean	Disable automatic terminal title updates
MATRIX_PERMISSION	string	Inlined json permissions config
MATRIX_DISABLE_DEFAULT_PLUGINS	boolean	Disable default plugins
MATRIX_DISABLE_LSP_DOWNLOAD	boolean	Disable automatic LSP server downloads
MATRIX_ENABLE_EXPERIMENTAL_MODELS	boolean	Enable experimental models
MATRIX_DISABLE_AUTOCOMPACT	boolean	Disable automatic context compaction
MATRIX_DISABLE_CLAUDE_CODE	boolean	Disable reading from .claude (prompt + skills)
MATRIX_DISABLE_CLAUDE_CODE_PROMPT	boolean	Disable reading ~/.claude/CLAUDE.md
MATRIX_DISABLE_CLAUDE_CODE_SKILLS	boolean	Disable loading .claude/skills
MATRIX_DISABLE_MODELS_FETCH	boolean	Disable fetching models from remote sources
MATRIX_DISABLE_MOUSE	boolean	Disable mouse capture in the TUI
MATRIX_FAKE_VCS	string	Fake VCS provider for testing purposes
MATRIX_DISABLE_FILETIME_CHECK	boolean	Disable file time checking for optimization
MATRIX_CLIENT	string	Client identifier (defaults to cli)
MATRIX_ENABLE_EXA	boolean	Enable Exa web search tools
MATRIX_SERVER_PASSWORD	string	Enable basic auth for serve/web
MATRIX_SERVER_USERNAME	string	Override basic auth username (default matrix)
MATRIX_MODELS_URL	string	Custom URL for fetching models configuration

---

Experimental

These environment variables enable experimental features that may change or be removed.

Variable	Type	Description
MATRIX_EXPERIMENTAL	boolean	Enable all experimental features
MATRIX_EXPERIMENTAL_ICON_DISCOVERY	boolean	Enable icon discovery
MATRIX_EXPERIMENTAL_DISABLE_COPY_ON_SELECT	boolean	Disable copy on select in TUI
MATRIX_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS	number	Default timeout for bash commands in ms
MATRIX_EXPERIMENTAL_OUTPUT_TOKEN_MAX	number	Max output tokens for LLM responses
MATRIX_EXPERIMENTAL_FILEWATCHER	boolean	Enable file watcher for entire dir
MATRIX_EXPERIMENTAL_OXFMT	boolean	Enable oxfmt formatter
MATRIX_EXPERIMENTAL_LSP_TOOL	boolean	Enable experimental LSP tool
MATRIX_EXPERIMENTAL_DISABLE_FILEWATCHER	boolean	Disable file watcher
MATRIX_EXPERIMENTAL_EXA	boolean	Enable experimental Exa features
MATRIX_EXPERIMENTAL_LSP_TY	boolean	Enable TY LSP for python files
MATRIX_EXPERIMENTAL_MARKDOWN	boolean	Enable experimental markdown features
MATRIX_EXPERIMENTAL_PLAN_MODE	boolean	Enable plan mode