CLI

Install and use the matrix CLI to log in, run agents, sync files, forward ports, and manage shell sessions on your Matrix computer.

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

Install the CLI

# 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

Verify

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.

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. Approve the CLI in that same browser tab once provisioning finishes.

Flags

Flag	Description
`--profile <name>`	Authenticate into a specific named profile
`--platform <url>`	Override the platform URL (default: `https://app.matrix-os.com`)
`--gateway <url>`	Override the gateway URL written into the profile on success

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

Flag	Description
`-it`	Interactive — attach a TTY to the remote command
`--session <name>`	Create or attach a named session (requires `-it`)
`-C`, `--cwd <dir>`	Working directory inside the Matrix home
`--no-mouse`	Drop mouse escape sequences before forwarding input

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

If a session already exists

When you pass --session <name> and a session with that name already exists, matrix run -it attaches to the existing session instead of failing. This means multiple team members or agents can all connect to the same named context.

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

If session creation fails

If matrix run -it, matrix shell new, or matrix shell attach fails to start a session, run matrix shell ls and connect to an existing session rather than retrying the same create path.

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

Flag	Description
`-p`, `--path <dir>`	Local folder to sync (default: `~/matrixos/`)
`-f`, `--folder <name>`	Gateway subtree to scope sync to. Default: full mirror of your sync root

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)

Flag	Description
`--force`	Overwrite the destination if it already exists
`--secret`	Mark the file as secret on upload (affects storage handling)

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.

Start the service first

The target service must already be running on the Matrix computer before forwarding traffic to it. Attach a terminal session to start your dev server there, then run matrix port forward in a separate local terminal.

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

Set a passphrase for your SSH key

When gh auth login generates an SSH key in the shell, choose a password (passphrase) for it — don't leave it empty. The key lives on your Matrix computer; a passphrase keeps it protected.

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:

Flag	Description
`--profile <name>`	Use a named profile (default: active profile from `profiles.json`)
`--gateway <url>`	Override gateway URL for this invocation
`--platform <url>`	Override platform URL for this invocation
`--token <jwt>`	Override auth token (useful in CI)
`--dev`	Shorthand for `--profile local`
`--json`	Emit machine-readable JSON (NDJSON for streaming commands)

CLI

On this page