Sandbase gives you instant, isolated copies of a real Postgres database — created by copy-on-write in seconds, safe to break, and thrown away when you're done. Every branch is a sandbox: delete data, run a migration, hand it to an agent, share it with a teammate — without touching production.

The sand CLI is how you create and manage those branches from your terminal, your CI, or an AI agent.

Install

macOS / Linux

curl -fsSL https://sandbase.dev/install.sh | bash

Windows (PowerShell)

irm https://sandbase.dev/install.ps1 | iex

npm (Node 18+)

npm install -g @sandbase/cli
# or run without installing:
npx @sandbase/cli --help

All three methods install the same self-contained binary — no runtime required. The installer places it at ~/.config/sand/bin/sand (%APPDATA%\sand\bin on Windows) and adds it to your PATH.

Quickstart

sand login                      # sign in (opens your browser)
sand connect postgres://…       # point Sandbase at an existing database
sand create feature-x           # branch it — a real-data copy in seconds
sand url                        # print the connection string for your branch
sand sql -c "select count(*) from users"
sand delete feature-x           # tear it down

Common commands

| Command | What it does | | --- | --- | | sand create <name> | Create a copy-on-write branch from the current branch. | | sand list | List branches in the project. | | sand switch <name> | Make a branch the active one for this directory. | | sand tree | Show the branch hierarchy. | | sand info [name] | Full detail for a branch (parent, size, status, expiry). | | sand url [name] | Print the branch connection string (-o env for DATABASE_URL=…). | | sand sql [-c "<query>"] | Open a SQL REPL, or run a one-off query. | | sand run -- <cmd> | Run any command with DATABASE_URL set to the branch. | | sand env pull | Merge the branch DSN into .env (owned keys only; --pull legacy form writes .env.sandbase). | | sand delete <name> | Delete a branch. |

Run sand --help for the complete reference, or sand <command> --help for any command.

Configuration

| Variable | Purpose | | --- | --- | | SANDBASE_API_KEY | Authenticate non-interactively (CI / agents) instead of sand login. | | SANDBASE_CONFIG_DIR | Override where config and the binary live (default: ~/.config/sand). |

Staying up to date

sand upgrade                    # latest release
sand upgrade --version 0.1.0    # a specific version

(If you installed via npm, update with npm update -g @sandbase/cli instead.)

Documentation

Full docs and guides: https://sandbase.dev/docs

© Sandbase. All rights reserved.