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 --org-token <org-uuid>

# 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.

Commands

Command	What it does
`auth`	Log in, log out, and check authentication status
`init`	Create `~/.baseshift/config` with default org and dub
`dub`	Create and manage dubs (cloud or self-hosted Helm)
`data-env`	Create and manage data environments and their snapshots
`server-clone`	Start, stop, and list clones on Baseshift servers
`local-clone`	Pull or run a dub's snapshot image with local Docker
`snapshot`	Create, check, and list snapshots of a dub
`mcp`	Run the Baseshift MCP server on stdio

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>"
}

Setting	Flag	Environment	Config key
Organization	`--org-token`	`BASESHIFT_ORG_TOKEN`	`orgToken`
Default dub	`--dub` / `--dub-uuid`	`BASESHIFT_DUB_UUID`	`dubUuid`

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"]
    }
  }
}

License

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

Development Status
- 5 - Production/Stable
Environment
- Console
Intended Audience
- Developers
License
- OSI Approved :: BSD License
Operating System
Programming Language
- Python :: 3
Topic
- Database
- Software Development :: Testing

Metadata

Development Status
- 5 - Production/Stable
Environment
- Console
Intended Audience
- Developers
License
- OSI Approved :: BSD License
Operating System
Programming Language
- Python :: 3
Topic
- Database
- Software Development :: Testing

Release files for baseshift 3.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for baseshift 3.4.0
File	Interpreter	ABI	Platform	Reset
baseshift-3.4.0-py3-none-win_amd64.whl 21.6 MB Sep 16, 2026	Python 3	none	Windows x86-64	Details
baseshift-3.4.0-py3-none-manylinux2014_x86_64.whl 21.1 MB Sep 16, 2026	Python 3	none	Linux glibc 2.17+ x86-64	Details
baseshift-3.4.0-py3-none-manylinux2014_aarch64.whl 19.3 MB Sep 16, 2026	Python 3	none	Linux glibc 2.17+ ARM64	Details
baseshift-3.4.0-py3-none-macosx_11_0_arm64.whl 20.9 MB Sep 16, 2026	Python 3	none	macOS 11.0+ ARM64	Details
baseshift-3.4.0-py3-none-macosx_10_9_x86_64.whl 21.9 MB Sep 16, 2026	Python 3	none	macOS 10.9+ x86-64	Details

Total release size: 104.8 MB

Release files / baseshift-3.4.0-py3-none-win_amd64.whl

Download URL	baseshift-3.4.0-py3-none-win_amd64.whl
Size	21.6 MB
Tags	Python 3 Windows x86-64
SHA-256 checksum How to use checksums	`0a2c15477170d596a48a2178c579b1caad1618d1df2c2f83962eda87482f0159`
BLAKE2b-256 checksum How to use checksums	`e656e494f2eb7f868d8f307242dfbe504e763998d70dc81da0685dbf7de7d0de`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.5`

Release files / baseshift-3.4.0-py3-none-manylinux2014_x86_64.whl

Download URL	baseshift-3.4.0-py3-none-manylinux2014_x86_64.whl
Size	21.1 MB
Tags	Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum How to use checksums	`a36f7a9b4bf908096f8269f4cb4ae0b458c45a74be35cb68b65bef7d545a402a`
BLAKE2b-256 checksum How to use checksums	`3d685079df3e3a10abcf6988012c0ab873a2e3771af68812f536be4e2fdf89ab`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.5`

Release files / baseshift-3.4.0-py3-none-manylinux2014_aarch64.whl

Download URL	baseshift-3.4.0-py3-none-manylinux2014_aarch64.whl
Size	19.3 MB
Tags	Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum How to use checksums	`ccc90e111aaac58e7c431025d2fce2eeb89454db140661e83a098e39567d43d2`
BLAKE2b-256 checksum How to use checksums	`af362ddb375bba7066d4cc5d653b3df70e5aadd562187c3688d133082534cfeb`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.5`

Release files / baseshift-3.4.0-py3-none-macosx_11_0_arm64.whl

Download URL	baseshift-3.4.0-py3-none-macosx_11_0_arm64.whl
Size	20.9 MB
Tags	Python 3 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`c853fc9ffc72531aa36a741e3f7da0720b9040ec235ec77074893de499b9496d`
BLAKE2b-256 checksum How to use checksums	`515e79d90dac2c956093bf13ac36ac6f95aa74c0cfaeb5de20df474f361c36bf`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.5`

Release files / baseshift-3.4.0-py3-none-macosx_10_9_x86_64.whl

Download URL	baseshift-3.4.0-py3-none-macosx_10_9_x86_64.whl
Size	21.9 MB
Tags	Python 3 macOS 10.9+ x86-64
SHA-256 checksum How to use checksums	`8237b401d4db168d293501703a2ffe6d9b9591712c79da0d83b0b3c784685044`
BLAKE2b-256 checksum How to use checksums	`fa8f9a26c8514d1347da2b7a139e26e33bab07f76a78d48f352a53a2c7827b08`
Upload date	Sep 16, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.5`