> ## Documentation Index
> Fetch the complete documentation index at: https://rakumux.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every rakumux command and option.

`rakumux` with no command opens the UI for the current folder. With a command it runs and exits.
Session names are looked up among the current folder's sessions; an id always works. Exit codes:
`0` success, `1` error (message on stderr), `2` wrong usage.

## Sessions

| Command | Does |
| - | - |
| `rakumux new [--name N] [--cwd DIR] [--cmd C]... [--detach] [-- PROGRAM ARGS...]` | Create a session in this folder and attach to it |
| `rakumux ls [--json] [--dead] [--folder DIR]... \| --all` | List this folder's sessions, those of the folders given, or of every folder |
| `rakumux attach <name\|id>` | One session full screen |
| `rakumux rename [<name\|id>] <new name>` | Rename a session (inside a session, a lone name renames itself) |
| `rakumux pin <name\|id>`, `rakumux unpin <name\|id>` | Pin a session first in its folder, or unpin it |
| `rakumux kill <name\|id> [--tree]` | End a session's program; the record stays |
| `rakumux rm <name\|id>` | Delete a session: end it and remove its record and scrollback |

### `rakumux new`

| Option | Meaning |
| - | - |
| `--name N` | Session name (default: generated) |
| `--cwd DIR` | Working directory (default: this folder). Outside this folder, it becomes the session's own folder. |
| `--cmd C` | A command typed into the shell after it starts; repeatable |
| `--detach` | Create the session without attaching. Required inside a session, since sessions can't attach. |
| `-- PROGRAM ARGS...` | A program to run instead of the login shell |

### `rakumux ls`

`--json` prints JSON, with each session's `folder`; `--dead` includes dead sessions; `--folder DIR`
lists another folder (repeatable); `--all` lists every folder. In the table, `*` marks the current
session and `^` a pinned one.

### `rakumux attach`

After the prefix `Ctrl-\`: `d` detaches, `>` / `<` go to the next / previous running session,
`n` starts a new session in the current directory, and `Ctrl-\` sends a literal `Ctrl-\`.

### `rakumux kill`

`--tree` also ends the sessions it created, recursively.

## Folders

| Command | Does |
| - | - |
| `rakumux folders [--json]` | List the folders sessions belong to |
| `rakumux folders add <dir>` | Add a folder, so it's listed even before it has sessions |
| `rakumux folders rm <dir>` | Forget a folder that has no sessions (the folder itself is untouched) |

`--json` prints `{"folders": [...], "projects": [...]}`: the same list twice, with `projects` kept
for older scripts.

## The server

| Command | Does |
| - | - |
| `rakumux daemon start` | Start the server if it isn't running |
| `rakumux daemon status [--json]` | Whether the server runs, and its statistics |
| `rakumux daemon restart [-y]` | Restart the server in place: sessions keep running. An older server that can't hand them over is stopped instead, after asking. |
| `rakumux daemon stop [-y]` | Stop the server, ending every running session. They don't come back on the next start. |
| `rakumux daemon logs [-n N] [-f]` | Print the server log (`-n` lines, default 50; `-f` keeps printing) |
| `rakumux --new-server` | Replace the running server with this Rakumux's (in place when it can), or start one, then open the UI |

`-y` skips the question before ending running sessions.

## Phone access

| Command | Does |
| - | - |
| `rakumux remote on [--port N]` | Turn phone access on (it stays on) and print the URL, token, link and QR code |
| `rakumux remote off` | Turn it off |
| `rakumux remote pair` | Show the URL, token, link and QR code again |
| `rakumux remote status [--json]` | Whether it's on, its URLs and the token's start |
| `rakumux remote token [--rotate]` | Print the token; `--rotate` makes a new one |

See [Phone access](https://rakumux.com/docs/phone/remote-access.md).

## Your Sprite and other machines

| Command | Does |
| - | - |
| `rakumux sprite connect [--token T] [--sprite NAME]` | Set up your Fly.io Sprite (made when missing) and connect to it; the token defaults to one found on this computer |
| `rakumux sprite status` | Which Sprite sessions go to, and whether it's reachable |
| `rakumux sprite disconnect` | Forget it and its token here; the Sprite and its files stay |
| `rakumux new --sprite` | A session on your Sprite, for this folder |
| `rakumux machine add <name> <url> --token T` | List and use the sessions of another machine running Rakumux (its remote listener's URL and token; `-` reads the token from stdin) |
| `rakumux machine ls [--json]` / `rakumux machine rm <name>` | The machines added / forget one (nothing there changes) |
| `rakumux new --machine <name>` | A session on that machine |

See [A Fly Sprite](https://rakumux.com/docs/remote/fly-sprites.md).

## Account

| Command | Does |
| - | - |
| `rakumux account login` | Sign in with a code approved in any browser (prints a link, a code and, on a terminal, a QR code) |
| `rakumux account status [--json]` | Who is signed in, whether AI session titles are on, and each live session's AI description |
| `rakumux account logout` | Sign out on this machine (AI session titles stop) |

See [Sign in](https://rakumux.com/docs/account/sign-in.md).

## For agents and scripts

`rakumux session` prints JSON. Inside a session it acts as that session (see
[What agents may do](https://rakumux.com/docs/agents/overview.md#what-agents-may-do)).

| Command | Does |
| - | - |
| `rakumux session list [--all]` | This folder's sessions: `{"sessions": [...]}` (`--all` includes dead ones) |
| `rakumux session get <name\|id>` | One session: `{"session": {...}}` |
| `rakumux session read <name\|id> [--source S] [--lines N] [--format F]` | A session's screen or recent output |
| `rakumux session wait <name\|id> --until U [--pattern P] [--timeout MS]` | Block until a session reaches a state, or the timeout (default 30000 ms) passes |
| `rakumux session report [options]` | Report this session's own state and result (inside a session only) |
| `rakumux session bind --agent A <conversation>...` | Claim agent conversations for this session (inside a session only); the OpenCode plugin uses it |
| `rakumux session hook-config --agent A` | Print hook configuration for an agent (`claude`, `codex`, `opencode`) |
| `rakumux session hook --agent A` | Receive agent hook JSON on stdin; used by the [activity hooks](https://rakumux.com/docs/agents/activity-hooks.md) |

* `read --source`: `visible` (the screen, the default), `recent` or `recent-unwrapped`. `--lines`
  sets the rows for recent sources. `--format`: `text` (default) or `ansi`.
* `wait --until`: `settled`, `idle`, `blocked`, `working`, `exited`, `reported` or `output` (with
  `--pattern`, a substring to wait for).
* `report`: `--state working|blocked|done|idle`, `--text` (a short status line shown in the list),
  `--summary` and `--file PATH` (repeatable, needs `--summary`), `--agent-kind`, `--agent-session-id`,
  and `--resume -- PROGRAM ARGS` (how to resume this session after a reboot).

```bash theme={null}
rakumux session report --state done --text "Tests pass" --summary "Fixed the flaky login test" --file src/login.rs
```

## Other commands

| Command | Does |
| - | - |
| `rakumux-mcp` | The MCP server, on stdio ([MCP server](https://rakumux.com/docs/agents/mcp.md)) |
| `rakumux-mcp opencode-plugin [--install]` | Print or install the OpenCode plugin |
| `rakumux-api [--port N] [--detach] [--remote-listen ADDR:PORT]...` | The local HTTP API ([API reference](https://rakumux.com/docs/api-reference/introduction.md)) |

Every command takes `--help`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.