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

# bead agent CLI commands

> Find bead agent CLI commands for prompts, events, turn control, approvals, desktop access, and credential profiles.

Run bead agent CLI commands to start coding-agent turns and control their events. Choose a supported [runner template](https://docs.bead.run/agents/runners.md) and [credential profile](https://docs.bead.run/agents/credentials.md) first.

## Prompt and observe

```bash theme={null}
bead prompt "$MACHINE_ID" 'Inspect the repository and report the test command' --cwd /root
bead events "$MACHINE_ID" --follow --after 0
bead status "$MACHINE_ID"
```

`prompt` accepts `--profile UUID`, `--model`, `--request-id UUID`, `--allow-credential-snapshot` and `--approve-tools`. Keep a stable request UUID when recovering the same turn submission. Credential snapshotting and tool approval are explicit options.

## Control a turn

| Command | Options |
| - | - |
| `bead steer ID TEXT` | Required `--turn UUID`; optional `--request-id UUID`. |
| `bead interrupt ID` | Required `--turn UUID`; optional `--request-id UUID`. |
| `bead approval ID` | Required `--turn UUID`, `--server-id`, `--decision accept\|decline\|cancel`. |
| `bead restart ID` | Restart the runner. |

Read [events, steering and approvals](https://docs.bead.run/agents/control.md) before acting on an uncertain turn state.

## Desktop

```bash theme={null}
bead desktop start "$MACHINE_ID"
bead desktop watch "$MACHINE_ID" --ttl-seconds 600
bead desktop status "$MACHINE_ID"
bead desktop takeover "$MACHINE_ID" --reason 'Please complete the sign-in'
```

`desktop share ID [--ttl-seconds 600]` also creates a watch link. Revoke a grant with `desktop share ID --revoke UUID`. `desktop release ID --outcome done|failed|skip [--note TEXT]` reads the controller session JSON from stdin.

Watch links are view-only. See [human takeover](https://docs.bead.run/agents/watch-takeover.md) for controller access and handback behavior.

## Credential profiles

| Command | Purpose |
| - | - |
| `bead profile-put UUID --name NAME` | Write profile material read privately from stdin. |
| `bead profile-list` | List profile metadata. |
| `bead profile-revoke UUID` | Revoke a profile. |
| `bead profile-delete UUID` | Delete a profile. |

Keep provider values out of argv and logs. Human subscription sign-in happens in the dashboard under Agents & credentials.


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