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

# Script Rakumux

> Start, watch and read sessions from shell scripts, or over the local HTTP API.

Everything you can do in the UI is a command too, so you can drive sessions from scripts, `make`
targets or other tools. Commands print JSON where a script needs it.

## Run a job in a session and wait for it

```bash theme={null}
# Start the test suite as the session's program, without attaching.
rakumux new --detach --name tests -- cargo test --workspace

# Wait up to ten minutes for it to finish.
rakumux session wait tests --until exited --timeout 600000

# Print the last 50 lines it wrote.
rakumux session read tests --source recent --lines 50 | jq -r .text
```

Because the session holds the job, you can watch it live in Rakumux at the same time, and it keeps
running if your script's terminal goes away.

## Wait for something to happen

`rakumux session wait <name|id> --until U` blocks until the session reaches a state, or until
`--timeout` milliseconds pass (default 30000). It prints `{"matched", "status", "lifecycle",
"reported", "reason"}`.

| `--until` | Waits until |
| - | - |
| `settled` | The agent stops working (idle, done or waiting for you), or the program ends |
| `idle`, `working`, `blocked` | The agent is in that state |
| `exited` | The program ends |
| `reported` | The session reports something |
| `output` | `--pattern` appears in its output |

```bash theme={null}
rakumux session wait dev-server --until output --pattern "ready on" --timeout 60000
```

## Read a session

`rakumux session read <name|id>` prints `{"text", "rows", "cols", "cursor", "truncated"}`.
`--source visible` (the default) is the screen; `recent` and `recent-unwrapped` are the last
`--lines` lines of history. `--format ansi` keeps colours.

## List sessions

```bash theme={null}
rakumux ls --all --json         # every folder's sessions
rakumux session list            # this folder's: {"sessions": [...]}
rakumux session get tests       # one: {"session": {...}}
```

Each session carries its `status`, `lifecycle`, `agent`, git context, the agent's latest output and
your last prompt (`agent_output`, `user_prompt`), and its terminal size.

## Over HTTP

For other languages, or anything that can't run a command, the
[local HTTP API](https://rakumux.com/docs/api-reference/introduction.md) serves the same operations on `127.0.0.1`, plus
WebSockets for session events and live terminals. It starts on demand:

```bash theme={null}
rakumux-api --detach
API=$(jq -r .url ~/.rakumux/api.json); TOKEN=$(jq -r .token ~/.rakumux/api.json)
curl -s -H "Authorization: Bearer $TOKEN" "$API/v1/sessions?all=true"
```

> [!NOTE]
>
> `jq` is used only by these examples; Rakumux doesn't need it.


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