CLI

The Matrix CLI is a single binary installed as matrix, matrixos, and mos. Use it to log in, attach to terminal sessions, sync files, forward ports, and run commands on your Matrix computer from any local terminal.

Install

# Homebrew (macOS / Linux)
brew install finnaai/tap/matrix

# npm (requires Node.js 20+)
npm install -g @finnaai/matrix

# Standalone binary — no Node.js required
curl -fsSL https://get.matrix-os.com | sh

matrix --version
matrix doctor

You can also run without installing using npx --yes @finnaai/matrix <command> or pnpm dlx @finnaai/matrix <command>. Auth tokens are stored in ~/.matrixos/ and reused across invocations.

Connect a coding agent over MCP

The Streamable HTTP integration with browser OAuth does not need a local Matrix CLI, but is not yet enabled. Use stdio until hosted rollout and browser sign-in are verified.

The stdio alternative remains available in Matrix CLI 0.3.16 and later. It runs a local bridge but executes tools on Matrix. Sign in, then configure your agent to launch the server command:

matrix login --profile cloud
matrix mcp serve --profile cloud

The second command is launched by your coding client as a stdio server. For clients with an mcpServers JSON configuration, merge this entry into the existing configuration after completing CLI login:

{
  "mcpServers": {
    "matrix": {
      "command": "matrix",
      "args": ["mcp", "serve", "--profile", "cloud"]
    }
  }
}

Ensure matrix is on the coding client's PATH, or use its absolute executable path. Clients with another configuration format need the same command and argument list. This connection uses your CLI profile; it does not use HTTP OAuth or the hosted plugin. Configure one Matrix connection per client to avoid duplicate tools.

The server uses your existing Matrix CLI login and exposes remote tools for:

• listing the Matrix computers your account can access;
• running a captured command on an explicitly selected computer;
• listing and creating persistent zellij terminal sessions and tabs;
• selecting a terminal tab and sending input to it;
• listing, reading, downloading, and uploading bounded files in Matrix home; and
• listing, searching, and reading Matrix chats.

Call list_computers first. Every other tool requires the computer's runtimeSlot, even when you only have one computer. Matrix credentials stay in the CLI profile and are never passed as MCP tool arguments.

Tab creation returns a stable tab ID. Pass that ID to select_terminal_tab; the displayed tab position can change when other tabs are created, closed, or reordered.

MCP file transfer is content-only: it does not grant access to paths on the coding agent's host. Text reads are limited to 256 KiB, binary transfers to 1 MiB, directory listings to 500 entries, terminal input to 60,000 bytes, and chat pages to 100 items. Uploads do not overwrite an existing file unless overwrite is explicitly enabled.

The MCP server routes its own tools to Matrix. It cannot disable or replace any local shell tool that the coding-agent host separately provides.

Log in

matrix login

This opens a browser for the device authentication flow. If you do not have a Matrix account yet, matrix login waits while the browser walks you through signup, checkout, and provisioning. After Checkout, Matrix keeps the device request active, shows build progress, and continues automatically when your computer is ready. You will not be asked to choose tools or start the build a second time. Approve the CLI in that same browser tab once provisioning finishes.

Flags

Local development shortcuts

# Skip the device flow; writes a stub token for a local dev stack
matrix login --dev

# Equivalent — uses the "local" profile and localhost endpoints
matrix login --profile local

--dev expects the local gateway running without MATRIX_AUTH_TOKEN (any bearer is accepted in that mode).

Run agents

matrix run starts a command on your Matrix computer and, with -it, attaches an interactive terminal to it.

matrix run -it -- claude
matrix run -it -- codex

Use --session to give the session a name so you and other agents can reattach to it later:

matrix run -it --session setup -- gh auth login
matrix run -it --session setup -- claude
matrix run -it --session review -- opencode

Flags

Non-interactive runs (without -it) capture stdout and stderr and print them locally. Exit code is forwarded from the remote process.

Connect to sessions

Your sessions live on your Matrix computer. The same sessions you see in the web shell are available from the CLI.

# List sessions
matrix shell ls

# Connect to an existing session
matrix shell connect main

# Create a session if it does not exist, then connect
matrix shell connect -c setup

# Create a new session without attaching
matrix shell new work

# Create and attach immediately
matrix shell new work --attach

# Remove a session
matrix shell rm old-session --force

connect and attach are aliases for the same subcommand. Pass -c (--create) to create the session if it does not exist before connecting — this is the recommended pattern for agent setup sessions.

Detach without stopping the session: press Ctrl-\ twice quickly. Reconnect any time with matrix shell connect <name>.

File sync

The sync daemon mirrors a local folder against your Matrix home directory and runs as a background service.

# Start syncing ~/matrixos (default local folder)
matrix sync

# Start syncing a specific local path
matrix sync ~/my-projects

# Scope sync to a subtree on the Matrix side
matrix sync ~/work --folder projects

# Check sync status
matrix sync status

# Pause and resume
matrix sync pause
matrix sync resume

matrix sync installs and starts the daemon on first run. Subsequent calls with the same path reuse the running daemon without restarting it.

Flags

Upload and download single files

Use matrix upload and matrix download for one-off file transfers without starting or touching the sync daemon.

matrix upload ./README.md projects/demo/README.md
matrix upload --force ./config.json system/config.json
matrix upload --secret ./api-key.txt system/secrets/api-key.txt

matrix download projects/demo/README.md ./README.remote.md
matrix download --force projects/demo/README.md ./README.remote.md

Flags (both commands)

Port forwarding

matrix port forward (or the top-level matrix forward alias) opens a local loopback listener and tunnels it to a port on your Matrix computer. The local listener always binds to 127.0.0.1. The remote target must also be a loopback address on the Matrix computer.

Spec format

<port>                       # local and remote port are the same
<localPort>:<remoteHost>:<remotePort>

Valid remote hosts: 127.0.0.1, localhost, [::1].

Examples

# Forward local 3000 to Matrix computer 127.0.0.1:3000
matrix port forward 3000

# Forward local 8080 to Matrix computer port 3000
matrix port forward 8080:127.0.0.1:3000

# Same via the top-level alias
matrix forward 3000

# Forward a Vite dev server running on the Matrix computer
matrix port forward 5173

After the forwarding is active, open http://127.0.0.1:<localPort> in your local browser. The command keeps running until you press Ctrl-C.

GitHub auth inside a Matrix session

Run gh auth login inside a Matrix terminal session rather than on your local machine. This registers credentials on the Matrix computer where your agents and workflows run.

matrix run -it --session setup -- gh auth login

Status and diagnostics

# Show active profile, gateway URL, and auth state
matrix status

# Show the authenticated Matrix identity
matrix whoami

# Run all health checks and print fix-it hints
matrix doctor

matrix doctor checks profile config, auth token validity, the local sync daemon, gateway reachability, and the shell backend. Run it before filing a support issue.

$ matrix doctor
OK profile
OK auth
FAIL daemon - Start sync with `mos sync`.
OK gateway
OK shell-backend
OK protocol

Global flags

Most commands accept these flags: