CLI Cheatsheet

A comprehensive reference of bauplan commands and their functionality.

Installation and Configuration

Command

Description

pip install bauplan --upgrade

Install the latest version of bauplan

bauplan version

Show the version of the bauplan CLI

bauplan help

Show available commands or help for one command

bauplan config set api_key "your_bauplan_key"

Configure your API key

bauplan info

Display current profile, active branch, user details, client/server versions and available runners

Branch Management

Command

Description

bauplan branch

List all available branches. Active branch marked with *

bauplan branch create <YOUR_USERNAME>.<BRANCH_NAME>

Create a new branch

bauplan checkout <YOUR_USERNAME>.<BRANCH_NAME>

Switch to specified branch

bauplan branch get <BRANCH_NAME>

Show all tables in specified branch

bauplan branch --all-zones

Show all open branches (not just user’s)

bauplan branch rm <YOUR_USERNAME>.<BRANCH_NAME>

Delete branch (only own branches)

bauplan branch merge <YOUR_USERNAME>.<BRANCH_NAME>

Merge branch into main (must be on main)

bauplan branch diff <BRANCH NAME>

Show differences between current and the specified branch.

Namespace Management

Command

Description

bauplan namespace create <NAMESPACE_NAME>

Create a new namespace in current branch

bauplan table --namespace <NAMESPACE_NAME>

List all tables in a namespace

Table Management and Import

Command

Description

bauplan table

List tables in active branch

bauplan table get <NAMESPACE_NAME>.<TABLE_NAME>

Show table metadata in active branch

bauplan table create --name <NAMESPACE_NAME>.<TABLE_NAME> --search-uri 's3://your-bucket/path/*.parquet'

Create empty table from schema

bauplan table create --name <NAMESPACE_NAME>.<TABLE_NAME> --search-uri <URI> --partitioned-by "<PARTITION_SPEC>"

Create partitioned table

bauplan table import --name <NAMESPACE_NAME>.<TABLE_NAME> --search-uri <URI>

Import data into existing table

bauplan table create-plan --name <NAMESPACE_NAME>.<TABLE_NAME> --search-uri <URI> --save-plan <FILE>

Generate table creation plan

bauplan table create-plan-apply --plan <FILE>

Apply table creation plan

bauplan table rm <NAMESPACE_NAME>.<TABLE_NAME>

Delete table from current branch

Note

The URI should be an S3 path, for example: ‘s3://your-bucket/path/*.parquet’

Parameters and Secrets

Command

Description

bauplan parameter set --name <PARAM_NAME> --value <VALUE> --type secret

Set a secret parameter

bauplan parameter set --name <PARAM_NAME> --value <VALUE>

Set a regular parameter

Pipeline and Job Execution

Command

Description

bauplan run

Execute pipeline in active branch

bauplan run --dry-run

Execute pipeline in memory only

bauplan run --head

Execute and show table previews

bauplan run --id <RUN_ID>

Reproduce a previous run

bauplan run --strict

Execute with data contract enforcement

bauplan run --detach

Submit job for detached execution

bauplan job get <JOB_ID>

Get status of a detached job

bauplan job ls

List recent jobs (last 24 hours)

bauplan job logs <JOB_ID>

Get logs from a detached job

bauplan job stop <JOB_ID>

Cancel a running detached job

Query

Command

Description

bauplan query "<SQL_QUERY>"

Execute query in active branch

bauplan query --branch <YOUR_USERNAME>.<BRANCH_NAME> "<SQL_QUERY>"

Execute query in specified branch

bauplan query --branch <YOUR_USERNAME>.<BRANCH_NAME> -f <FILE.SQL>

Execute query with specified namespace

bauplan query -f <FILE.SQL>

Execute query from file

bauplan query --no-trunc "<SQL_QUERY>"

Execute query without truncating output

Important

  • Always prefix branch names with your username (e.g., <YOUR_USERNAME>.<BRANCH_NAME>)

  • The --dry-run flag is required when:

    • Working in the main branch

    • Testing changes without materialization

  • Materialization is not allowed in the main branch

  • Detached runs logs are persisted for 24 hours

  • Branch names must follow the format username.branchname except for the main branch