baseshift

Command-line client for Baseshift. Create dubs (masked or subsetted copies of a source database), take snapshots, and start clones for development and testing.

Install

pip install baseshift

Platform wheels ship for:

• macOS (Intel and Apple Silicon)
• Linux (x86_64 and arm64)
• Windows (amd64)

The default install talks to clones over WireGuard. For Tailscale, install the companion extra so both packages stay on the same version:

pip install 'baseshift[ts]'

Confirm the install:

baseshift --version
baseshift --help

Quick start

# Browser OAuth (default). Use --method=direct for email/password.
baseshift auth login

# Optional: write ~/.baseshift/config (org token and default dub)
baseshift init

# Create a cloud dub with demo data, or point at your own Postgres.
baseshift dub create --name my-dub --use-demo-db --encryption-password MyKey123
baseshift dub list

# Snapshot, then start a clone and print connection details.
baseshift snapshot create --dub my-dub --wait
baseshift server-clone start --dub my-dub
baseshift server-clone list --dub my-dub
baseshift server-clone stop

--dub accepts a name or a UUID. A name is resolved by the API; pass --org-token (or set BASESHIFT_ORG_TOKEN / orgToken in config) when the same name exists in more than one org. A UUID never needs --org-token.

dub create and dub list use your only organization when --org-token is omitted. When you belong to more than one organization, pass --org-token.

Commands

Run baseshift <command> --help (and baseshift dub create -h) for flags. Common dub actions: create, list, describe, status, health-check, validate-values, configure-source, subset, masking.

Cloud dub against your database

baseshift dub create --name my-dub \
  --hostname mydb.example.com --database acme --username app \
  --password-stdin --encryption-password MyKey123

Self-hosted dub (Helm values)

baseshift dub create --deployment self-hosted --name my-onprem-dub \
  --hostname mydb.example.com --database acme --username dubhub \
  --password-stdin --registry-type none
baseshift dub validate-values --values-file values.yaml

Local Docker clone

baseshift local-clone pull --dub my-dub
baseshift local-clone run --dub my-dub -- --publish 5432:5432

Configuration

Values resolve as CLI flag → environment variable → ~/.baseshift/config → default.

baseshift init writes JSON to ~/.baseshift/config:

{
    "orgToken": "<org-uuid>",
    "dubUuid": "<dub-uuid>"
}

Useful environment variables:

• BASESHIFT_VERBOSE=1 — DEBUG logs and full tracebacks (same as -v)
• BASESHIFT_DISABLE_SENTRY=1 — disable error telemetry
• BASESHIFT_HELM_BIN — override the bundled Helm binary used by dub validate-values

MCP

baseshift mcp runs an MCP server on stdio (start/stop clones and related tools). Log in with baseshift auth login first. Example Cursor config:

{
  "mcpServers": {
    "baseshift": {
      "command": "baseshift",
      "args": ["mcp"]
    }
  }
}

Links

• Product: baseshift.com
• App: app.baseshift.com
• PyPI: pypi.org/project/baseshift

License

BSD 2-Clause. See LICENSE, THIRD-PARTY-NOTICES, and LICENSES-Apache-2.0-Helm.txt (bundled Helm).