# CLI

Everyday Buddy Sandbox workflows with the bdy CLI - create, connect, run commands, copy files, expose ports, take snapshots, and inspect the machine.

`bdy` is Buddy's command-line interface. It covers the whole platform - projects, pipelines, tunnels, artifacts, domains - and Sandboxes are a first-class part of it.

```bash
npm install -g bdy
bdy login
bdy proj link
```

Installation and authentication are covered in [CLI getting started](/docs/cli/getting-started.md). The flag-by-flag command reference is generated from the CLI itself and lives under [bdy sandbox](/docs/cli/sandbox.md). This page covers the workflows you will actually repeat.

All examples use the `sb` alias for `sandbox`.

## Create a Sandbox from the CLI

There are three ways to bring a Sandbox up, and they differ only in where the starting state comes from: a clean OS image, a snapshot you prepared earlier, or a YAML definition.

### From an OS image

The default path. You get a clean Ubuntu machine - `ubuntu:24.04` unless you ask for `ubuntu:22.04` with `--os` - and describe what has to happen on it.

**A bare machine.** Nothing but the preinstalled toolchain, ready in seconds:

```bash
bdy sb create -i my-sandbox
```

**A working environment.** Code fetched, dependencies installed, application started, and the command returns only once all of it is up:

```bash
bdy sb create -i my-sandbox \
  --fetch \
  --boot-command "npm install" \
  --app-command "npm start" \
  --wait-for-apps
```

### From a snapshot

Skips the setup entirely - dependencies are already installed in the snapshot, so the Sandbox is usable the moment it boots.

```bash
bdy sb create -i my-sandbox --snapshot node-base
```

See [Snapshots](/docs/sandboxes/snapshots.md) for how to prepare one.

### From a YAML definition

The reproducible path: the whole configuration lives in a file you keep next to your code.

```bash
bdy sb create --yaml @./sandbox.yml
```

The `@` prefix marks a file path - without it, the value is read as inline YAML. Every field the file can contain is documented in [Sandbox YAML](/docs/yaml/yaml-sandbox.md).

### Waiting for the Sandbox

Three flags hold the command back, in increasing order of patience:

| Flag | Returns when |
| :--- | :--- |
| `--wait-for-running` | the machine is up |
| `--wait-for-configured` | setup commands have finished |
| `--wait-for-apps` | applications are running |

Each takes an optional timeout in seconds, for example `--wait-for-apps 300`.

Every flag accepted by all three paths is listed in [`bdy sandbox create`](/docs/cli/sandbox/create.md). The same settings from the UI and YAML side are described in [Sandbox configuration](/docs/sandboxes/configuration.md).

## Work inside

```bash
bdy sb connect my-sandbox                                   # interactive shell
bdy sb exec command my-sandbox "npm test" --wait            # one-off command
bdy sb exec command my-sandbox "print(1+1)" --runtime PYTHON --wait
bdy sb cp ./dist my-sandbox:/home/buddy/app/dist --ignore "node_modules/**"
bdy sb cp my-sandbox:/home/buddy/report.json ./report.json
```

**Runtimes** available to `exec command` are `BASH` (default), `PYTHON`, `JAVASCRIPT` and `TYPESCRIPT`.

Full flag lists live in [`bdy sandbox exec command`](/docs/cli/sandbox/exec/command.md) and [`bdy sandbox cp`](/docs/cli/sandbox/cp.md). For what happens on the machine - which user the command runs as, which directory it starts in, who owns transferred files - read [Running commands in a Sandbox](/docs/sandboxes/running-commands.md) and [Sandbox files](/docs/sandboxes/files.md).

## Expose

```bash
bdy sb ep add my-sandbox -e 3000                  # HTTP on port 3000
bdy sb ep add my-sandbox -e 3306 -t TCP -n db     # raw TCP
bdy sb ep add my-sandbox -s /home/buddy/site      # serve a directory, no server needed
bdy sb ep list my-sandbox
```

The server has to listen on `0.0.0.0`, otherwise the endpoint stays unreachable. Access control, custom headers and region selection are flags on the same command.

All available flags are listed in [`bdy sandbox endpoint add`](/docs/cli/sandbox/endpoint/add.md) and [`bdy sandbox endpoint list`](/docs/cli/sandbox/endpoint/list.md). Endpoint types, authorization and address format are explained in [Sandbox endpoints](/docs/sandboxes/endpoints.md).

## Apps

```bash
bdy sb app add my-sandbox "npm run worker"
bdy sb app list my-sandbox
bdy sb app logs my-sandbox <app-id>
bdy sb app stop my-sandbox <app-id>
```

`app list` is where the IDs and statuses come from - the other commands take an app ID, not the command string.

The remaining subcommands - `start`, `status`, `remove` - are listed in [`bdy sandbox app`](/docs/cli/sandbox/app.md). How applications are defined and controlled from the interface is covered in [Sandbox applications](/docs/sandboxes/apps.md).

## Snapshots

```bash
bdy sb snapshot create my-sandbox -n node-base --wait
bdy sb snapshot list my-sandbox
bdy sb create -i my-sandbox-2 --snapshot node-base
```

Getting and deleting snapshots is documented in [`bdy sandbox snapshot`](/docs/cli/sandbox/snapshot.md). When snapshots are worth taking and what restoring one does is covered in [Sandbox snapshots](/docs/sandboxes/snapshots.md).

## Inspect

```bash
bdy sb list
bdy sb get my-sandbox
bdy sb status my-sandbox
bdy sb yaml my-sandbox
bdy sb logs my-sandbox          # setup and fetch log
```

`sb logs` covers boot commands and fetch sources only. Application output is in `bdy sb app logs`, command output in `bdy sb exec logs`.

Output formats and filters are documented per command: [`bdy sandbox list`](/docs/cli/sandbox/list.md), [`bdy sandbox get`](/docs/cli/sandbox/get.md), [`bdy sandbox yaml`](/docs/cli/sandbox/yaml.md) and [`bdy sandbox logs`](/docs/cli/sandbox/logs.md). Reading the same output in the interface is described in [Sandbox logs](/docs/sandboxes/logs.md).

## Lifecycle

```bash
bdy sb stop my-sandbox
bdy sb start my-sandbox
bdy sb restart my-sandbox
bdy sb destroy my-sandbox
```

Each command has its own page: [`bdy sandbox start`](/docs/cli/sandbox/start.md), [`bdy sandbox stop`](/docs/cli/sandbox/stop.md), [`bdy sandbox restart`](/docs/cli/sandbox/restart.md) and [`bdy sandbox destroy`](/docs/cli/sandbox/destroy.md). What survives a stop, what a timeout does and what wakes a stopped machine is explained in [Sandbox lifecycle](/docs/sandboxes/lifecycle.md).

## Working across workspaces and projects

Every command accepts `-w/--workspace` and `-p/--project`, and both can come from the `BUDDY_WORKSPACE` and `BUDDY_PROJECT` variables instead of being typed each time. Inside a linked project directory you can usually skip both.

## From inside a Sandbox

The CLI is preinstalled in every Sandbox, and there is a shortcut scoped to the machine you are on - see [Self-management](/docs/sandboxes/self-management.md).


---
Original source: https://buddy.works/docs/sandboxes/cli