Reference
CLI reference
Every modem command and flag.
The core
| Command | What it does |
|---|
modem | Where things stand: sessions, running jobs, recent files. |
modem claude | Opens the agent on your computer, or reattaches. Also codex; kimi coming soon. |
modem run "…" | Runs a task headless and returns immediately. |
| Command | What it does |
|---|
modem setup | Account, computer and tools in one pass. Runs automatically if you skip it. |
modem setup --new | Provisions a fresh computer: use if yours is unreachable for good. |
modem connect <tool> | github, claude, codex. Persists on the computer. |
modem doctor | Diagnoses the computer and the connection. |
modem version | Prints the version of the installed binary. |
Jobs
| Command | What it does |
|---|
modem run "…" | Starts a job. Flags below. |
modem logs [id] [-f] | Output of the current job, or the one you name. |
modem stop [id] | Stops it and keeps what it produced. |
modem ls | Every session and every job. |
Flag of run | Effect |
|---|
--agent claude|codex | Which agent. Default claude. |
--in <folder> | Working directory on the computer. |
--timeout 45m | Hard limit. Default 30m, maximum 4h. |
--shell | Plain shell command, no agent. |
-f | Follow immediately. |
Files
| Command | What it does |
|---|
modem push <path> | Sends a file, or a whole folder with its environment files. |
modem pull <path> [dest] | Brings something back. |
modem files [path] | Lists the computer's disk. |
modem shell | A plain shell up there. |
Keys
| Key | Effect |
|---|
| Ctrl+Q | Detach from an interactive session; it keeps running. |
| Ctrl+C | Goes to the agent, as it would locally. |
Aliases and older names
login still works for setup, sync for push, get for pull, ps and jobs for ls, sh for shell. Mistyping a command suggests the closest one instead of dumping the whole help.
modem login --code XXXX-XXXX is the reconnection flow: it exchanges a one-time code from the site for your account token, on a new machine or after a reinstall. Reconnect codes are valid for 60 minutes.
Files and environment
| Name | Purpose |
|---|
~/.modem/config.json | Your account token and your computer's address. Written by modem setup. |
MODEM_URL | Target a machine directly, bypassing the account. Development only. |
MODEM_TOKEN | That machine's access token. |