CLI reference

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.

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.

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.

For agents and scripts

rakumux session prints JSON. Inside a session it acts as that session (see 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

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

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)
`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)

Every command takes --help.

Get started

Where to run it

Workflows

Using Rakumux

Coding agents

Account and AI titles

Phone access

Reference

Sessions

`rakumux new`

`rakumux ls`

`rakumux attach`

`rakumux kill`

Folders

The server

Phone access

Your Sprite and other machines

Account

For agents and scripts

Other commands

​Sessions

​rakumux new

​rakumux ls

​rakumux attach

​rakumux kill

​Folders

​The server

​Phone access

​Your Sprite and other machines

​Account

​For agents and scripts

​Other commands

Sessions

`rakumux new`

`rakumux ls`

`rakumux attach`

`rakumux kill`

Folders

The server

Phone access

Your Sprite and other machines

Account

For agents and scripts

Other commands