Command reference

Generated from beachside schema. Run bun run --cwd apps/docs cli:generate after changing a command.

Global flags

These work with every command.

Flag	Description
--json	Print one JSON document on stdout (also BEACHSIDE_JSON=1)
--profile <name>	Profile from beachside.json (also BEACHSIDE_PROFILE)
--provider <id>	Official provider from environment credentials (also BEACHSIDE_PROVIDER)
--config <path>	Config file (default ~/.config/beachside/beachside.json, also BEACHSIDE_CONFIG)
--state-dir <dir>	State store folder (default ~/.config/beachside/state, also BEACHSIDE_STATE_DIR)
-V, --version	Print the CLI version

Output

With --json, stdout holds exactly one document: {ok:true,data} or {ok:false,error:{code,message,retryable,outcome,hint?,known?,details?}}. Diagnostics always go to stderr.

exec, sh and run exit with the remote command’s exit code; their JSON data is {exitCode,stdout,stderr,truncated}, and run adds sandbox {name,id,kept}. Without –json, output streams as it arrives where the provider supports it.

Exit codes

Code	Meaning
0	success
1	other failure
2	usage error; fix the command
3	not found
4	unsupported by this provider or profile, adapter missing or broken, npm or a password-manager CLI not installed, or store limit reached
5	authentication or permission failure, or an unreadable password-manager secret
6	outcome unknown: an effect may have happened, inspect before retrying
7	retryable: rate limit, capacity or unavailable before any effect
8	partial: some steps were confirmed; read error.known
125	exec/run: the CLI or provider failed; details in the error
130	interrupted by SIGINT (129 for SIGHUP, 143 for SIGTERM); an interrupted run still destroys its sandbox

create

Create a sandbox and print its name.

beachside create [--name <name>] [--image <oci-ref> | --prepared <id> | --snapshot <name>] [--network <policy>] [--ttl <duration>] [--env K=V]...

Flag	Description
--name <name>	Store name (default: generated, like sb-1a2b3)
--image <oci-ref>	OCI image, e.g. python:3.12; default is the profile’s image
--prepared <id>	Provider-prepared image id (template, snapshot name)
--network <policy>	blocked or internet; default is the profile’s policy
--label <k=v>	Label to set (repeatable)
--env <K=V>	Environment variable for every command in the sandbox (repeatable; K alone copies it from here)
--env-file <path>	Read K=V lines into the sandbox environment (repeatable; –env wins)
--build	Build –image now if this provider needs a build and none is recorded
--ttl <duration>	Destroy the sandbox after this long even if nothing removes it, e.g. 30m or 2h; default is the profile’s lifetime
--snapshot <name>	Restore a snapshot recorded by beachside snapshot create instead of an image
--retry <duration>	Keep retrying for up to this long when the provider refuses before creating anything (rate limit, capacity), e.g. 5m
--if-not-exists	Return the named sandbox if it is still alive instead of failing

Examples:

beachside create --name web --network internet
beachside create --name job-42 --if-not-exists --json
beachside create --name ci --env-file .env --env API_TOKEN
beachside create --name job-42 --ttl 1h
beachside create --name job-42 --retry 5m --json

ls

List sandboxes in the store with their current state.

beachside ls [--offline | --remote]

Flag	Description
--offline	Show stored records without asking providers
--remote	List the profile’s sandboxes from the provider instead of the store

Examples:

beachside ls
beachside ls --json
beachside ls --remote --provider daytona

adopt

Add a sandbox from the provider’s listing to the store so other commands reach it.

beachside adopt <id> [--name <name>]

Flag	Description
--name <name>	Store name (default: generated, like sb-1a2b3)

Examples:

beachside ls --remote
beachside adopt 4f1c2a --name worker

inspect

Show a sandbox’s state, expiry and reference.

beachside inspect <sandbox>

Examples:

beachside inspect web --json

rm

Destroy sandboxes and remove their records.

beachside rm <sandbox>... | --all [--force]

Flag	Description
--all	Every sandbox in this store
--force	Also destroy sandboxes this CLI did not create, or drop unreachable records

Examples:

beachside rm web
beachside rm --all

gc

Destroy the provider’s sandboxes that carry the given labels, such as a killed job’s.

beachside gc --label k=v... [--older-than <duration>] [--dry-run]

Flag	Description
--label <k=v>	Only sandboxes with this label set at create (repeatable; all must match)
--older-than <duration>	Only sandboxes the provider says were created at least this long ago, e.g. 2h
--dry-run	List what would be destroyed and change nothing

Examples:

beachside gc --label run=$GITHUB_RUN_ID
beachside gc --label ci=true --older-than 2h --dry-run

exec

Run a command in a sandbox; exits with the command’s exit code.

beachside exec <sandbox> [--cwd <dir>] [--env K=V]... [--stdin] -- <command> [args...]

Flag	Description
--cwd <dir>	Working directory in the sandbox
--env <K=V>	Environment variable for this command (repeatable; K alone copies it from here)
--env-file <path>	Read K=V lines into this command’s environment (repeatable; –env wins)
--stdin	Send this process’s stdin to the command
--stdin-file <path>	Send a local file as the command’s stdin
--timeout <duration>	Execution deadline, e.g. 90s or 10m (default 300s)
--max-output <size>	Captured output limit for buffered and –json output, e.g. 1m
--no-stream	Print the output when the command ends instead of as it arrives

Exits with the remote command’s exit code; failures of the CLI itself exit 125.

Examples:

beachside exec web -- ls -la /
beachside exec web --cwd /work --env CI=1 -- npm test

sh

Run a shell script in a sandbox; exits with its exit code.

beachside sh <sandbox> '<script>' | beachside sh <sandbox> -- '<script>'

Flag	Description
--cwd <dir>	Working directory in the sandbox
--env <K=V>	Environment variable for this command (repeatable; K alone copies it from here)
--env-file <path>	Read K=V lines into this command’s environment (repeatable; –env wins)
--stdin	Send this process’s stdin to the command
--stdin-file <path>	Send a local file as the command’s stdin
--timeout <duration>	Execution deadline, e.g. 90s or 10m (default 300s)
--max-output <size>	Captured output limit for buffered and –json output, e.g. 1m
--no-stream	Print the output when the command ends instead of as it arrives

Exits with the remote command’s exit code; failures of the CLI itself exit 125.

Examples:

beachside sh web 'cd /work && make test'
beachside sh web -- '-n is fine here'

run

Create a sandbox, run one command, and always destroy it.

beachside run [create flags] [exec flags] [--keep] [--push <path>] -- <command> [args...]

Flag	Description
--name <name>	Store name (default: generated, like sb-1a2b3)
--image <oci-ref>	OCI image, e.g. python:3.12; default is the profile’s image
--prepared <id>	Provider-prepared image id (template, snapshot name)
--network <policy>	blocked or internet; default is the profile’s policy
--label <k=v>	Label to set (repeatable)
--env <K=V>	Environment variable for this command (repeatable; K alone copies it from here)
--env-file <path>	Read K=V lines into this command’s environment (repeatable; –env wins)
--build	Build –image now if this provider needs a build and none is recorded
--ttl <duration>	Destroy the sandbox after this long even if nothing removes it, e.g. 30m or 2h; default is the profile’s lifetime
--snapshot <name>	Restore a snapshot recorded by beachside snapshot create instead of an image
--retry <duration>	Keep retrying for up to this long when the provider refuses before creating anything (rate limit, capacity), e.g. 5m
--cwd <dir>	Working directory in the sandbox
--stdin	Send this process’s stdin to the command
--stdin-file <path>	Send a local file as the command’s stdin
--timeout <duration>	Execution deadline, e.g. 90s or 10m (default 300s)
--max-output <size>	Captured output limit for buffered and –json output, e.g. 1m
--no-stream	Print the output when the command ends instead of as it arrives
--keep	Keep the sandbox and print its name on stderr
--push <path>	Send a local folder to ~/work first and run the command there
--exclude <glob>	Skip matching paths (repeatable; a pattern without / matches any name)
--include-ignored	Send every file, not only git-tracked and unignored ones

Exits with the remote command’s exit code; failures of the CLI itself exit 125.

Examples:

beachside run -- python3 -c 'print(2 + 2)'
beachside run --network internet -- curl -sI https://example.com
beachside run --push . --timeout 15m --ttl 30m -- sh -c 'npm ci && npm test'

image

Build OCI images for providers that need it, and list, delete or forget the builds.

beachside image build <oci-ref> [--name <name>] [--refresh] | ls [--remote] | inspect <name> | rm <name> [--force] | forget <name>

Flag	Description
--name <name>	Record name for a build (default: from the reference, like python-3-12)
--refresh	Build again even if this reference is recorded
--remote	List the images on the provider for this profile, not the local records
--force	Delete a recorded image this CLI did not verifiably create

Examples:

beachside image build python:3.12 --provider e2b
beachside create --image python:3.12 --provider e2b
beachside image ls
beachside image ls --remote --provider e2b
beachside image rm python-3-12
beachside image forget python-3-12

snapshot

Capture a sandbox as a snapshot, and list, inspect, delete or forget snapshots.

beachside snapshot create <sandbox> [--name <name> [--replace]] | ls [--remote] | inspect <name> | rm <name> [--force] | forget <name>

Flag	Description
--name <name>	Record name for a capture (default: -snap)
--replace	Capture –name again; the old snapshot is deleted once the new one exists
--remote	List the snapshots on the provider for this profile, not the local records
--force	Delete a recorded snapshot this CLI did not verifiably capture

Examples:

beachside snapshot create web --name deps
beachside create --snapshot deps --name web-2
beachside run --snapshot deps -- npm test
beachside snapshot create web --name deps --replace
beachside snapshot ls
beachside snapshot rm deps

cp

Copy files or directories to or from a sandbox.

beachside cp [-r] <src> <dst>   (one side is <sandbox>:/path)

Flag	Description
--no-clobber	Fail instead of overwriting an existing file
-r, --recursive	Copy directories as one tar archive (needs tar in the sandbox)
--exclude <glob>	Skip matching paths (repeatable; a pattern without / matches any name)

Examples:

beachside cp ./app.py web:/work/app.py
beachside cp web:/work/out.json ./out.json
beachside cp -r ./src web:/work --exclude node_modules
beachside cp -r web:/work/coverage ./coverage

push

Send a local folder’s git-tracked and unignored files into a sandbox.

beachside push <sandbox>[:/dir] [path]   (default: . to ~/work in the sandbox)

Flag	Description
--exclude <glob>	Skip matching paths (repeatable; a pattern without / matches any name)
--include-ignored	Send every file, not only git-tracked and unignored ones

Examples:

beachside push ci
beachside push ci:/srv/app ./app --exclude '*.log'
beachside exec ci --cwd /srv/app -- npm test

cat

Print a file from a sandbox.

beachside cat <sandbox>:/path

Examples:

beachside cat web:/etc/os-release

doctor

Check config, credentials and the provider connection without creating anything.

beachside doctor

Examples:

beachside doctor --provider e2b

adapter

Install, list or remove the adapters the CLI loads, in ~/.config/beachside/adapters.

beachside adapter add <provider|package>[@version]... | ls | rm <provider|package>...

Examples:

beachside adapter add e2b
beachside adapter add daytona vercel --json
beachside adapter add @acme/beachside-adapter@1.2.0
beachside adapter ls
beachside adapter rm e2b

providers

List official providers, whether their adapter is installed and their credentials set.

beachside providers

Examples:

beachside providers --json

skill

Print the agent skill for this CLI, or install it for your coding agents.

beachside skill [install [--project]]

Flag	Description
--project	Install into this folder’s .agents/skills (and .claude/skills) instead of your home

Examples:

beachside skill
beachside skill install
beachside skill install --project

completion

Print a shell completion script for zsh, bash or fish.

beachside completion <zsh|bash|fish>

Examples:

source <(beachside completion zsh)   # in ~/.zshrc
source <(beachside completion bash)  # in ~/.bashrc
beachside completion fish > ~/.config/fish/completions/beachside.fish