CLI

The Matrix CLI is the local command line for your Matrix computer. It logs in, attaches to remote sessions, syncs files, uploads and downloads one-off non-secret files, and exposes machine-readable output for automation.

Install

# Homebrew
brew install finnaai/tap/matrix

# npm
npm install -g @finnaai/matrix

Verify:

matrix --version
matrix doctor

Log in

matrix login --profile cloud
matrix whoami

If you do not have a Matrix account yet, matrix login --profile cloud waits while the browser walks you through signup, checkout, and provisioning.

Shell sessions

Matrix sessions are backed by zellij on your Matrix computer.

matrix shell ls
matrix shell new main --attach
matrix shell connect main
matrix shell connect -c setup
matrix shell rm old-session --force

Detach without killing the session:

Ctrl-\ Ctrl-\

Run commands in Matrix

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

Use named sessions for setup and agent workflows so the browser, CLI, and agents can reattach to the same context.

Files

matrix sync ~/matrixos
matrix upload ./README.md projects/demo/README.md
matrix download projects/demo/README.md ./README.remote.md

Authenticate tools inside Matrix

For coding agents and developer tools, prefer browser/device login inside the Matrix VPS. Run matrix run -it --session setup -- claude, matrix run -it --session setup -- codex, or matrix run -it --session setup -- gh auth login, then complete that tool's own login flow in the remote terminal.

Profiles

matrix profile ls
matrix profile use local
matrix --profile local shell ls
matrix --dev shell ls

The default cloud profile points at https://app.matrix-os.com. The local profile points at a development stack.

More commands

The complete CLI command reference is still available in the legacy CLI guide.

CLI