CLI

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.

npm install -g bdy
bdy login
bdy proj link
$$$

Installation and authentication are covered in CLI getting started. The flag-by-flag command reference is generated from the CLI itself and lives under bdy sandbox. 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:

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:

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.

bdy sb create -i my-sandbox --snapshot node-base
$

See Snapshots 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.

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.

Waiting for the Sandbox

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

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. The same settings from the UI and YAML side are described in Sandbox configuration.

Work inside

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 and bdy sandbox cp. 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 and Sandbox files.

Expose

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 agent runs inside the Sandbox, so a server bound to 127.0.0.1 or localhost is reachable the same way as one on 0.0.0.0. Access control, custom headers and region selection are flags on the same command.

All available flags are listed in bdy sandbox endpoint add and bdy sandbox endpoint list. Endpoint types, authorization and address format are explained in Sandbox endpoints.

Apps

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. How applications are defined and controlled from the interface is covered in Sandbox applications.

Snapshots

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. When snapshots are worth taking and what restoring one does is covered in Sandbox snapshots.

Fetch sources

bdy sb fetch add my-sandbox --ref main
bdy sb fetch ls my-sandbox
bdy sb fetch refetch my-sandbox :default
$$$

:default points at the fetch into the app directory. Other fetches are addressed by their target directory. Adding artifacts and public repositories is covered in bdy sandbox fetch and Fetching Git repositories and artifacts.

Inspect

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, bdy sandbox get, bdy sandbox yaml and bdy sandbox logs. Reading the same output in the interface is described in Sandbox logs.

Lifecycle

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, bdy sandbox stop, bdy sandbox restart and bdy sandbox destroy. What survives a stop, what a timeout does and what wakes a stopped machine is explained in Sandbox lifecycle.

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.