Skip to main content

CLI Guide

Use the CLI to create dubs, take snapshots, and launch server or local clones from your terminal.

Installation​

To install the Baseshift CLI, run:

pipx install baseshift

To upgrade the Baseshift CLI, run:

pipx upgrade baseshift

Authentication and profile setup​

Login​

To use the Baseshift CLI, you must first authenticate. Run:

baseshift auth login

This command opens your browser so you can log in and approve access. If the browser does not open automatically, copy the URL printed in the terminal and open it manually.

Once the login is approved, you can continue working with the CLI normally.

For CI/CD or other non-interactive environments, create a system user and authenticate with direct login by passing --email and --password:

baseshift auth login --method=direct \
  --email "$BASESHIFT_USER_EMAIL" \
  --password "$BASESHIFT_USER_PASSWORD"

Create a profile (optional)​

Profiles let you set a default organization and dub, so you don't need to specify them for every command. To create a profile, run:

baseshift init

You'll be prompted to enter your org token and dub. You can find these values in the Dub details in the Dubs screen. The organization token identifies which organization a command applies to, it is not used for authentication.

Most commands accept --dub (name or UUID) and --org-token. If you omit them, the CLI uses environment variables or your active profile.

Environment variables​

You can set defaults with:

  • BASESHIFT_ORG_TOKEN - organization token
  • BASESHIFT_DUB_UUID - default dub UUID

When a value is specified in multiple places, the CLI uses the following precedence: CLI flag → environment variable → profile.

export BASESHIFT_ORG_TOKEN=your-org-token
export BASESHIFT_DUB_UUID=your-dub-uuid

baseshift snapshot create
baseshift server-clone start

Create a dub​

You can create a dub using Baseshift Cloud or deploy it self-hosted on Kubernetes.

Try Baseshift with demo data on Baseshift Cloud

The fastest way to get started. Creates a dub in Baseshift cloud using a demo PostgreSQL database provided by Baseshift.

baseshift dub create --name my-dub \
  --use-demo-db \
  --encryption-password <your-encryption-password>

Connect your own database on Baseshift Cloud

Baseshift Cloud currently supports PostgreSQL sources.

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

Self-hosted​

For self-hosted deployments, the CLI creates a Helm values.yaml that you can use to deploy Baseshift to your Kubernetes cluster. After generation, review and complete the file as needed - see the Kubernetes values.yaml reference.

baseshift dub create --deployment self-hosted \
  --name my-dub \
  --hostname mydb.example.com \
  --database acme \
  --username app \
  --password-stdin \
  --registry-type none

Source credentials​

When connecting your own database, provide credentials in one of these ways:

  • Username and password - pass --username with either --password or --password-stdin. Prefer --password-stdin so the password is not on the command line. You can also set --port (defaults to the engine default) and --engine (postgres by default; Baseshift Cloud supports Postgres only).

    echo "$DB_PASSWORD" | baseshift dub create --name my-dub \
      --hostname mydb.example.com \
      --database acme \
      --username app \
      --password-stdin \
      --encryption-password <your-encryption-password>

  • AWS Secrets Manager ARN (self-hosted only) - pass --aws-secret-arn with --hostname and --database. Credentials come from the secret; do not pass --username, --password, or --password-stdin.

    baseshift dub create --deployment self-hosted \
      --name my-dub \
      --hostname mydb.example.com \
      --database acme \
      --aws-secret-arn arn:aws:secretsmanager:region:account:secret:name \
      --registry-type none

You can also reuse an existing source with --source-id <uuid> instead of providing the connection details again.

Encryption password and registry​

--encryption-password is an alphanumeric key (letters and numbers only) used to encrypt Docker snapshot images.

  • Baseshift Cloud (including --use-demo-db) - required.
  • Self-hosted - required only when Docker snapshot images are enabled (--registry-type is not none). If you omit it when a registry is set, the generated Helm values.yaml includes a placeholder you must fill in before installing.

--registry-type is for self-hosted deployments only. It selects where Docker snapshot images are pushed so you can run local clones. Default is none (no Docker snapshot images). Supported values:

  • none
  • harbor
  • jfrog-artifactory
  • gcp-artifact-registry
  • azure-acr
  • aws-ecr

CLI values use kebab-case; they are written as snake_case in the generated values.yaml (for example jfrog-artifactory → jfrog_artifactory).

Additional options​

  • --snapshot-schedule - Set the snapshot schedule to @daily (default), @weekly, @monthly, or never.
  • --masking-policy-file - Apply a masking policy before the first snapshot.
  • --subset-policy-file - Apply a subset policy before the first snapshot.
  • --no-watch - Return immediately after creating the dub instead of waiting for it to become ready.
  • --retry --dub <name-or-uuid> - Resume setup after an error.

To check the status of a dub:

baseshift dub status --dub <name-or-uuid>

For interactive setup and infrastructure detail, see the Dub setup wizard.

Create a snapshot​

baseshift snapshot create [--dub <name-or-uuid>] [--tag <tag>] [--wait]

Creates a new snapshot for the specified dub.

Optional flags:

  • --dub - Defaults to the value in your active profile if not provided.
  • --org-token - Defaults to the value in your active profile if not provided.
  • --tag - Tag to attach to the new snapshot.
  • --wait - Wait until the snapshot is ready before returning.

Related commands:

baseshift snapshot status [--dub <name-or-uuid>]
baseshift snapshot list [--dub <name-or-uuid>]

For UI-based snapshot creation, see Creating a Snapshot.

Server clones​

Server clones run on the replication server. On Baseshift Cloud, the CLI establishes a secure tunnel and prints connection details.

Start a server clone​

baseshift server-clone start [--dub <name-or-uuid>] [-i]

Launches a new server clone and returns the connection details.

Optional flags:

  • --dub - Defaults to the value in your active profile if not provided.
  • --org-token - Defaults to the value in your active profile if not provided.
  • --tag - Snapshot tag to clone from (defaults to the latest snapshot).
  • -i - Start the clone and connect to it using the native database CLI (for example, psql).
  • --timeout - Seconds of inactivity before the clone shuts down. Defaults to 840 (14 minutes) if omitted.
  • --grace - Seconds after startup during which inactivity is not checked. Defaults to 120 (2 minutes) if omitted.

Stop a server clone​

baseshift server-clone stop [--clone-uuid <clone-uuid>]

Stops a clone. By default, it stops the last clone you started.

Optional flags:

  • --clone-uuid - UUID of the clone to stop.
  • --all - Stop every clone you started.
  • --dub - When used with --all, limit to clones for that dub.

List server clones​

baseshift server-clone list

Lists running clones and their uptime.

For UI-based server clones, see Server Clones.

Local clones​

Pull and run a dub's Docker snapshot image on your machine:

baseshift local-clone pull [--dub <name-or-uuid>] [--tag <tag>]
baseshift local-clone run [--dub <name-or-uuid>] [--tag <tag>]

By default, both commands use the latest snapshot. Use --tag to select a specific snapshot.

Pass extra Docker arguments after --. For registry auth, encryption password, and advanced container options, see Local Clones.

Getting help​

To see all available commands and options, run:

baseshift -h

For flags on a specific command:

baseshift <command> -h