> ## 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 machine CLI commands

> Find bead machine CLI commands to create and manage machines, execute work, transfer files, and forward ports.

Pass the actual machine ID returned by creation when using bead machine CLI commands. Keep it available for later inspection and cleanup.

## Create and inspect

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead create --template base --size small --timeout 300
bead create --template devbox --size medium --kind persistent --idle-timeout 900
bead list --limit 20
bead inspect "$MACHINE_ID"
```

`create` defaults to template `agents` and size `medium`. Options: `--template`, `--size`, `--timeout`, `--kind temporary|persistent`, `--idle-timeout` and `--profile UUID`. Idle timeout accepts seconds or `never`. Use [machine sizes](https://docs.bead.run/machines/sizes.md) and [lifetime](https://docs.bead.run/run-work/lifetime.md) to choose resources and retention.

`list` accepts `--limit` from 1–100 (default 20) and `--cursor` for the returned pagination token.

## Lifecycle

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead pause "$MACHINE_ID"
bead resume "$MACHINE_ID"
bead delete "$MACHINE_ID"
```

Inspect durable state when a response is uncertain. Deletion and retained snapshot lifetimes are separate.

## Commands and files

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead exec "$MACHINE_ID" 'uname -a' --cwd /root
bead put "$MACHINE_ID" /tmp/input.txt --input ./input.txt
bead get "$MACHINE_ID" /tmp/input.txt --output ./download.txt
bead files "$MACHINE_ID" ListDir --input list-directory.json
bead diff "$MACHINE_ID" --cwd /root
```

`exec` takes a shell command string and defaults to `/root`. `get` writes bytes to stdout when `--output` is omitted. Native `files` operations are `Stat`, `MakeDir`, `Move`, `ListDir` and `Remove`; their request body comes from a JSON file. See [file operations](https://docs.bead.run/connect/files.md).

## Application ports

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead open "$MACHINE_ID" --port 3000
bead port-forward "$MACHINE_ID" --port 3000 --local-port 8080
bead network "$MACHINE_ID"
bead ports "$MACHINE_ID" --input ports.json
```

`open` and `port-forward` use authenticated localhost forwarding. An omitted local port allocates one. `ports` configures raw ports from a JSON array file; [raw ports](https://docs.bead.run/connect/raw-ports.md) have a separate access model.

## Bounded jobs

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead run --from base --size small --push . --timeout 900 -- sh -lc 'echo hello'
```

`run` provisions, uploads, executes and cleans up. See [portable CI](https://docs.bead.run/ci/portable.md) for source selection, limits and exit behavior.


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