CLI reference

Complete reference documentation for the Bauplan Command Line Interface (CLI).

Quick Navigation

Core Sections

Global Flags - Flags available for all commands
Top-Level Commands - Quick command overview
Command Reference - Detailed documentation

Commands version • run • rerun • checkout • query • commit • info • branch • tag • namespace • table • parameter • config • job

Common Workflows Branch and Version Control • Data Exploration • Pipeline Execution • Job Management • Table Operations

Global Flags

These flags are available for all Bauplan CLI commands:

Flag	Short	Type	Default	Description	Environment Variable
`--profile`	`-p`	string	"default"	Name of the profile to use	`$BAUPLAN_PROFILE`
`--env`	`-e`	string	"prod"	Bauplan environment to use	`$BPLN_ENV`
`--api-key`	`-k`	string	-	Bauplan API key to use	`$BAUPLAN_API_KEY`
`--output`	`-o`	string	"tty"	Output format (options: tty, json)	-
`--debug`	`-d`	boolean	false	Run in Debug mode	`$BPLN_DEBUG`
`--verbose`	`-x`	boolean	false	Print verbose logs	`$BPLN_VERBOSE`
`--feature-flag`	-	string (repeatable)	-	Set a feature flag. Format: key=value. Can be used multiple times.	`$BPLN_FEATURE_FLAGS`
`--client-timeout`	-	int	1800	Timeout (in seconds) for client operations (-1 = no timeout)	-
`--help`	`-h`	boolean	-	Show help	-

Top-Level Commands

bauplan <command> [flags]

Available commands:

version - Show the version of the Bauplan CLI
run - Execute a bauplan run
rerun - Re-execute a previous bauplan run
branch - Manage branches
tag - Manage tags
commit - Show commit history for a ref
namespace - Manage namespaces
table - Manage tables
query - Run an SQL query
parameter - Manage project parameters
config - Configure Bauplan CLI settings
info - Print debug information about the current environment
job - Manage jobs
checkout - Set the active branch
help, h - Shows a list of commands or help for one command

Command Reference

version

Show the version of the Bauplan CLI.

Usage:

bauplan version [flags]

Flags:

-help, -h - Show help

Example:

bauplan version

run

Execute a bauplan run (pipeline execution).

Usage:

bauplan run [flags]

Flags:

Flag	Short	Type	Default	Description
`--arg`	`-a`	string (repeatable)	-	Arguments to pass to the job. Format: key=value
`--project-dir`	`-p`	string	"."	Path to the root Bauplan project directory
`--cache`	-	string	-	Set the cache mode. [on, off]
`--summary-no-trunc`	-	boolean	false	Do not truncate summary output
`--preview`	-	string	-	Set the preview mode. [on, off, head, tail]
`--strict`	-	string	-	Exit upon encountering runtime warnings (e.g., invalid column output)
`--runner-node`	-	string	"bauplan-runner"	Node to run the job on. If not set, the job will be run on the default node for the project
`--param`	-	string (repeatable)	-	Set a parameter for the job. Format: key=value. Can be used multiple times
`--namespace`	`-n`	string	-	Namespace to run the job in. If not set, the job will be run in the default namespace for the project
`--ref`	`-r`	string	-	Ref or branch name from which to run the job
`--dry-run`	-	boolean	false	Dry run the job without materializing any models
`--transaction`	`-t`	string	-	Run the dag as a transaction. Will create a temporary branch where models are materialized. Once all models succeed, it will be merged to branch in which this run is happening in
`--detach`	`-d`	boolean	false	Run the job in the background instead of streaming logs
`--priority`	-	int	-	Set the job priority (1-10, where 10 is highest priority)
`--help`	`-h`	-	-	Show help

Examples:

# Run pipeline in current directory
bauplan run

# Dry run without materializing models
bauplan run --dry-run

# Run with strict mode and preview
bauplan run --strict --preview head

# Run on specific branch with custom parameters
bauplan run --ref main --param env=prod

# Run in background
bauplan run --detach

# Run with specific node
bauplan run --runner-node custom-node --namespace my_ns

rerun

Re-execute a previous bauplan run.

Usage:

bauplan rerun [flags]

Flags:

Flag	Short	Type	Default	Description
`--job-id` / `--id`	-	string	-	Run ID to re-run (required)
`--arg`	`-a`	string (repeatable)	-	Arguments to pass to the job. Format: key=value
`--summary-no-trunc`	-	boolean	false	Do not truncate summary output
`--preview`	-	string	-	Set the preview mode. [on, off, head, tail]
`--strict`	`-s`	string	-	Exit upon encountering runtime warnings
`--runner-node`	-	string	"bauplan-runner"	Node to run the job on
`--namespace`	`-n`	string	-	Namespace to run the job in
`--ref`	`-r`	string	-	Ref or branch name from which to run the job
`--cache`	-	string	-	Set the cache mode. [on, off]
`--dry-run`	-	boolean	false	Dry run the job without materializing any models
`--transaction`	`-t`	string	-	Run the dag as a transaction
`--help`	`-h`	-	-	Show help

Examples:

# Re-run a specific job
bauplan rerun --job-id abc123def456

# Re-run with new parameters
bauplan rerun --id abc123def456 --arg env=staging

# Re-run as dry run
bauplan rerun --job-id abc123def456 --dry-run

checkout

Set the active branch.

Usage:

bauplan checkout [flags] <BRANCH_NAME>

Flags:

Flag	Short	Type	Default	Description
`--branch`	`-b`	string	-	Create a new branch (alias for "branch create")
`--from-ref`	-	string	-	Ref from which to create when using --branch. If not specified, default is active branch
`--help`	`-h`	-	-	Show help

Examples:

# Checkout existing branch
bauplan checkout main

# Checkout user branch
bauplan checkout username.dev_branch

# Create and checkout new branch from main
bauplan checkout --branch username.new_feature --from-ref main

# Create and checkout new branch from active branch
bauplan checkout --branch username.new_feature

query

Run an SQL query against the lakehouse.

Usage:

bauplan query [flags] [SQL]

Flags:

Flag	Short	Type	Default	Description
`--no-trunc`	-	boolean	false	Do not truncate output
`--cache`	-	string	-	Set the cache mode. [on, off]
`--file`	`-f`	string	-	Read query from file
`--arg`	`-a`	string (repeatable)	-	Arguments to pass to the job. Format: key=value
`--ref`	`-r`	string	-	Ref or branch name to run query against
`--max-rows`	-	int	10	Limit number of returned rows (use --all-rows to disable)
`--namespace`	`-n`	string	-	Namespace to run the query in. If not set, the query will be run in the default namespace
`--all-rows`	-	boolean	false	Do not limit returned rows. Supercedes --max-rows
`--priority`	-	int	-	Set the job priority (1-10, where 10 is highest priority)
`--help`	`-h`	-	-	Show help

Examples:

# Run query inline
bauplan query "SELECT * FROM raw_data.customers LIMIT 10"

# Run query from file
bauplan query --file query.sql

# Run query with no row limit
bauplan query --all-rows "SELECT COUNT(*) FROM raw_data.orders"

# Run query on specific branch
bauplan query --ref main "SELECT * FROM my_table"

# Run query in specific namespace
bauplan query --namespace raw_data "SELECT * FROM customers LIMIT 5"

# Run query with full output (no truncation)
bauplan query --no-trunc "SELECT * FROM wide_table"

commit

Show commit history for a ref.

Usage:

bauplan commit [flags]

Flags:

Flag	Short	Type	Default	Description
`--ref`	`-r`	string	-	Ref or branch name to get the commits from (defaults to active branch)
`--message`	-	string	-	Filter by message content (string or regex like "^something.*$")
`--author-username`	-	string	-	Filter by author username (string or regex)
`--author-name`	-	string	-	Filter by author name (string or regex)
`--author-email`	-	string	-	Filter by author email (string or regex)
`--property`	-	string (repeatable)	-	Filter by a property. Format: key=value
`--limit` / `--max-count`	`-n`	int	10	Limit the number of commits to show
`--pretty`	-	string	"medium"	Pretty-print format [oneline, short, medium, full, fuller]
`--help`	`-h`	-	-	Show help

Examples:

# Show recent commits on active branch
bauplan commit

# Show commits from specific branch
bauplan commit --ref main

# Show more commits
bauplan commit --limit 20

# Show commits by specific author
bauplan commit --author-username john_doe

# Show commits matching message pattern
bauplan commit --message "^fix.*" --limit 5

# Show commits in oneline format
bauplan commit --pretty oneline --limit 10

# Show all commits
bauplan commit --limit 0

info

Print debug information about the current environment.

Usage:

bauplan info [flags]

Flags:

-help, -h - Show help

Example:

bauplan info

branch

Manage branches.

Usage:

bauplan branch <command> [flags]

Available Subcommands:

ls, list - List all available branches (default action)
create - Create a new branch
rm, delete - Delete a branch
get - Get information about a branch
checkout - Set the active branch
diff - Show the diff between two branches
merge - Merge a branch into the active branch
rename - Rename a branch

branch ls / branch list

List all available branches.

Usage:

bauplan branch ls [flags] [BRANCH_NAME]

Flags:

Flag	Short	Type	Default	Description
`--all-zones`	`-a`	boolean	false	Show all branches, including those from other namespaces (users)
`--name`	`-n`	string	-	Filter by name
`--user`	`-u`	string	-	Filter by user
`--limit`	-	int	0	Limit the number of branches to show
`--help`	`-h`	-	-	Show help

Examples:

# List user's own branches
bauplan branch ls

# List all branches
bauplan branch ls --all-zones

# Filter by name
bauplan branch ls --name "dev"

# Filter by user
bauplan branch ls --user username

# Limit results
bauplan branch ls --limit 5

branch create

Create a new branch.

Usage:

bauplan branch create [flags] <BRANCH_NAME>

Flags:

Flag	Type	Default	Description
`--from-ref`	string	-	Ref from which to create. If not specified, default is active branch
`--if-not-exists`	boolean	false	Do not fail if the branch already exists
`--help, -h`	-	-	Show help

Examples:

# Create branch from active branch
bauplan branch create username.dev_branch

# Create branch from specific ref
bauplan branch create username.new_feature --from-ref main

# Create branch without failing if exists
bauplan branch create username.my_branch --if-not-exists

branch rm / branch delete

Delete a branch.

Usage:

bauplan branch rm [flags] <BRANCH_NAME>

Flags:

Flag	Type	Default	Description
`--if-exists`	boolean	false	Do not fail if the branch does not exist
`--help, -h`	-	-	Show help

Examples:

# Delete a branch
bauplan branch rm username.old_branch

# Delete without failing if not exists
bauplan branch rm username.maybe_branch --if-exists

branch get

Get information about a branch.

Usage:

bauplan branch get [flags] <BRANCH_NAME>

Flags:

Flag	Short	Type	Default	Description
`--namespace`	`-n`	string	-	Filter by namespace
`--help`	`-h`	-	-	Show help

Examples:

# Get branch information
bauplan branch get username.dev_branch

# Get with namespace filter
bauplan branch get username.branch --namespace raw_data

branch checkout

Set the active branch.

Usage:

bauplan branch checkout [flags] <BRANCH_NAME>

Flags:

-help, -h - Show help

Examples:

bauplan branch checkout main
bauplan branch checkout username.dev_branch

branch diff

Show the diff between two branches.

Usage:

bauplan branch diff [flags] <BRANCH_NAME_A> [BRANCH_NAME_B]

Flags:

Flag	Short	Type	Default	Description
`--namespace`	`-n`	string	-	Filter by namespace
`--help`	`-h`	-	-	Show help

Examples:

# Diff between active branch and another
bauplan branch diff username.dev_branch

# Diff between two specific branches
bauplan branch diff main username.dev_branch

# Diff with namespace filter
bauplan branch diff username.branch1 username.branch2 --namespace raw_data

branch merge

Merge a branch into the active branch.

Usage:

bauplan branch merge [flags] <BRANCH_NAME>

Flags:

Flag	Type	Default	Description
`--commit-message`	string	-	Optional commit message
`--help, -h`	-	-	Show help

Examples:

# Merge branch into active branch
bauplan branch merge username.dev_branch

# Merge with custom commit message
bauplan branch merge username.feature --commit-message "Merge feature updates"

Important: You must be on the target branch before merging. For example, to merge into main:

bauplan branch checkout main
bauplan branch merge username.feature_branch

branch rename

Rename a branch.

Usage:

bauplan branch rename [flags] <BRANCH_NAME> <NEW_BRANCH_NAME>

Flags:

-help, -h - Show help

Examples:

bauplan branch rename username.old_name username.new_name

tag

Manage tags.

Usage:

bauplan tag <command> [flags]

Available Subcommands:

ls, list - List all available tags (default action)
create - Create a new tag
rm, delete - Delete a tag
rename - Rename a tag

List all available tags.

Usage:

bauplan tag ls [flags]

Flags:

Flag	Type	Default	Description
`--name`	string	-	Filter by name (can be a regex)
`--limit`	int	0	Limit the number of tags to show
`--help, -h`	-	-	Show help

Examples:

# List all tags
bauplan tag ls

# Filter by name pattern
bauplan tag ls --name "v.*"

# Limit results
bauplan tag ls --limit 10

tag create

Create a new tag.

Usage:

bauplan tag create [flags] <TAG_NAME>

Flags:

Flag	Type	Default	Description
`--from-ref`	string	-	Ref from which to create. If not specified, default is active branch
`--if-not-exists`	boolean	false	Do not fail if the tag already exists
`--help, -h`	-	-	Show help

Examples:

# Create tag from active branch
bauplan tag create v1.0

# Create tag from specific ref
bauplan tag create v1.0 --from-ref main

# Create without failing if exists
bauplan tag create v1.0 --if-not-exists

tag rm / tag delete

Delete a tag.

Usage:

bauplan tag rm [flags] <TAG_NAME>

Flags:

Flag	Type	Default	Description
`--if-exists`	boolean	false	Do not fail if the tag does not exist
`--help, -h`	-	-	Show help

Examples:

# Delete a tag
bauplan tag rm v1.0

# Delete without failing if not exists
bauplan tag rm v1.0 --if-exists

tag rename

Rename a tag.

Usage:

bauplan tag rename [flags] <TAG_NAME> <NEW_TAG_NAME>

Flags:

-help, -h - Show help

Examples:

bauplan tag rename v1.0 v1.0-stable

namespace

Manage namespaces.

Usage:

bauplan namespace <command> [flags]

Available Subcommands:

ls, list - List available namespaces
create - Create a new namespace
rm, delete, drop - Drop a namespace from the data catalog

namespace ls / namespace list

List available namespaces.

Usage:

bauplan namespace ls [flags] <NAMESPACE>

Flags:

Flag	Short	Type	Default	Description
`--ref`	`-r`	string	-	Ref or branch name to get the namespaces from (defaults to active branch)
`--limit`	-	int	0	Limit the number of namespaces to show
`--help`	`-h`	-	-	Show help

Examples:

# List namespaces on active branch
bauplan namespace ls

# List namespaces on specific branch
bauplan namespace ls --ref main

# Limit results
bauplan namespace ls --limit 10

namespace create

Create a new namespace.

Usage:

bauplan namespace create [flags] <NAMESPACE>

Flags:

Flag	Short	Type	Default	Description
`--branch`	`-b`	string	-	Branch to create the namespace in (defaults to active branch)
`--commit-body`	-	string	-	Optional commit body to append to the commit message
`--if-not-exists`	-	boolean	false	Do not fail if the namespace already exists
`--help`	`-h`	-	-	Show help

Examples:

# Create namespace on active branch
bauplan namespace create raw_data

# Create namespace on specific branch
bauplan namespace create transformed_data --branch main

# Create without failing if exists
bauplan namespace create my_namespace --if-not-exists

namespace rm / namespace delete / namespace drop

Drop a namespace from the data catalog.

Usage:

bauplan namespace rm [flags] <NAMESPACE>

Flags:

Flag	Short	Type	Default	Description
`--branch`	`-b`	string	-	Branch to delete the namespace from (defaults to active branch)
`--commit-body`	-	string	-	Optional commit body to append to the commit message
`--if-exists`	-	boolean	false	Do not fail if the namespace does not exist
`--help`	`-h`	-	-	Show help

Examples:

# Delete namespace from active branch
bauplan namespace rm old_namespace

# Delete from specific branch
bauplan namespace rm old_namespace --branch main

# Delete without failing if not exists
bauplan namespace rm maybe_namespace --if-exists

table

Manage tables.

Usage:

bauplan table <command> [flags]

Available Subcommands:

ls, list - List all available tables
get - Get information about a table
rm, delete, drop - Drop a table from the data catalog
create - Create a new table
create-plan - Create a plan for a new table
create-plan-apply - Apply a table create plan manually
create-external - Create an external read-only Iceberg table
import - Import data to an existing table
revert - Revert a table to a previous state from a source ref

table ls / table list

List all available tables.

Usage:

bauplan table ls [flags]

Flags:

Flag	Short	Type	Default	Description
`--namespace`	`-n`	string	-	Namespace to get the table from
`--ref`	`-r`	string	-	Ref or branch name to get the tables from (defaults to active branch)
`--limit`	-	int	0	Limit the number of tables to show
`--help`	`-h`	-	-	Show help

Examples:

# List tables on active branch
bauplan table ls

# List tables in specific namespace
bauplan table ls --namespace raw_data

# List tables from specific branch
bauplan table ls --ref main

# Limit results
bauplan table ls --limit 20

table get

Get information about a table.

Usage:

bauplan table get [flags] TABLE_NAME

Flags:

Flag	Short	Type	Default	Description
`--ref`	`-r`	string	-	Ref or branch name to get the table from (defaults to active branch)
`--help`	`-h`	-	-	Show help

Examples:

# Get table info from active branch
bauplan table get customers

# Get table info from specific branch
bauplan table get customers --ref main

# Get table info with namespace prefix
bauplan table get raw_data.customers

table rm / table delete / table drop

Drop a table from the data catalog (does not free up storage).

Usage:

bauplan table rm [flags] TABLE_NAME

Flags:

Flag	Short	Type	Default	Description
`--branch`	`-b`	string	-	Branch to delete the table from (defaults to active branch)
`--commit-body`	-	string	-	Optional commit body to append to the commit message
`--if-exists`	-	boolean	false	Do not fail if the table does not exist
`--help`	`-h`	-	-	Show help

Examples:

# Delete table from active branch
bauplan table rm old_table

# Delete from specific branch
bauplan table rm old_table --branch main

# Delete without failing if not exists
bauplan table rm maybe_table --if-exists

table create

Create a new table.

Usage:

bauplan table create [flags]

Flags:

Flag	Short	Type	Default	Description
`--name`	-	string	-	Name of the table to create (required)
`--search-uri`	-	string	-	URI search string to S3 bucket containing parquet files (e.g., s3://bucket/path/a/*)
`--branch`	`-b`	string	-	Branch to create the table in (defaults to active branch)
`--namespace`	`-n`	string	-	Namespace the table is in. If not set, the default namespace in your account will be used
`--partitioned-by`	-	string	-	Partition the table by the given columns
`--replace`	`-r`	boolean	false	Replace the existing table, if it exists
`--arg`	`-a`	string (repeatable)	-	Arguments to pass to the job. Format: key=value
`--priority`	-	int	-	Set the job priority (1-10)
`--help`	`-h`	-	-	Show help

Examples:

# Create table from S3 data
bauplan table create --name customers --search-uri s3://mybucket/customers/*.parquet --namespace raw_data

# Create table with partitioning
bauplan table create --name orders --search-uri s3://mybucket/orders/*.parquet --partitioned-by date_column

# Create table on specific branch
bauplan table create --name products --search-uri s3://mybucket/products/*.parquet --branch main

# Replace existing table
bauplan table create --name customers --search-uri s3://mybucket/customers/*.parquet --replace

table create-plan

Create a plan for a new table (preview before applying).

Usage:

bauplan table create-plan [flags]

Flags:

Flag	Short	Type	Default	Description
`--name`	-	string	-	Name of the table to create (required)
`--search-uri`	-	string	-	URI search string to S3 bucket containing parquet files
`--branch`	`-b`	string	-	Branch to create the table in
`--namespace`	`-n`	string	-	Namespace the table is in
`--partitioned-by`	-	string	-	Partition the table by the given columns
`--replace`	`-r`	boolean	false	Replace the existing table, if it exists
`--save-plan`	`-p`	string	-	Filename to write the plan to
`--arg`	`-a`	string (repeatable)	-	Arguments to pass to the job
`--help`	`-h`	-	-	Show help

Examples:

# Create plan and save to file
bauplan table create-plan --name customers --search-uri s3://mybucket/customers/*.parquet --save-plan plan.json

# Create plan without saving
bauplan table create-plan --name products --search-uri s3://mybucket/products/*.parquet

table create-plan-apply

Apply a table create plan manually.

Usage:

bauplan table create-plan-apply [flags]

Flags:

Flag	Type	Default	Description
`--plan`	string	-	Plan file to apply (required)
`--arg`	`-a`	string (repeatable)	-
`--priority`	int	-	Set the job priority (1-10)
`--help`	`-h`	-	Show help

Examples:

# Apply previously created plan
bauplan table create-plan-apply --plan plan.json

table create-external

Create an external read-only Iceberg table from existing data.

Usage:

bauplan table create-external [flags]

Description: Two modes:

FROM METADATA: Create an external table that points to the metadata of an existing Iceberg table.
FROM PARQUET: Create table by scanning parquet files matching a search pattern.

Flags:

Flag	Short	Type	Default	Description
`--name`	-	string	-	Name of the external table to create (required)
`--metadata-json-uri`	-	string	-	URI to Iceberg metadata.json file (e.g., s3://bucket/metadata.json)
`--search-pattern`	-	string (repeatable)	-	Search pattern for parquet files (e.g., s3://bucket/2025/*.parquet). Can be specified multiple times
`--branch`	`-b`	string	-	Branch to create the table in (defaults to active branch)
`--namespace`	`-n`	string	-	Namespace for the table
`--overwrite`	-	boolean	false	Overwrite the table if it already exists
`--detach`	`-d`	boolean	false	Run the job in the background (only for parquet mode)
`--arg`	`-a`	string (repeatable)	-	Arguments to pass to the job (only for parquet mode)
`--priority`	-	int	-	Set the job priority (1-10, where 10 is highest) (only for parquet mode)
`--help`	`-h`	-	-	Show help

Examples:

# Create external table from Iceberg metadata
bauplan table create-external --name events --metadata-json-uri s3://bucket/metadata.json --namespace raw_data

# Create external table from parquet files
bauplan table create-external --name events --search-pattern "s3://bucket/data/*.parquet" --namespace raw_data

# Create external table with multiple search patterns
bauplan table create-external --name events --search-pattern "s3://bucket/2024/*.parquet" --search-pattern "s3://bucket/2025/*.parquet" --namespace raw_data

# Create and overwrite existing table
bauplan table create-external --name events --search-pattern "s3://bucket/data/*.parquet" --overwrite

table import

Import data to an existing table.

Usage:

bauplan table import [flags]

Flags:

Flag	Short	Type	Default	Description
`--name`	-	string	-	Name of table where data will be imported into (required)
`--branch`	`-b`	string	-	Branch to import into (defaults to active branch)
`--search-uri`	-	string	-	URI search string (e.g., s3://bucket/path/a/*) (required)
`--continue-on-error`	-	boolean	false	Don't fail if 1/N files fail to import
`--import-duplicate-files`	-	boolean	false	Force importing files without checking what was already imported
`--best-effort`	-	boolean	false	Ignore new columns. Only import matching columns
`--namespace`	`-n`	string	-	Namespace the table is in
`--detach`	`-d`	boolean	false	Run the job in the background
`--arg`	`-a`	string (repeatable)	-	Arguments to pass to the job
`--priority`	-	int	-	Set the job priority (1-10)
`--help`	`-h`	-	-	Show help

Examples:

# Import data to existing table
bauplan table import --name customers --search-uri s3://bucket/customers/new_data/*.parquet

# Import with continue on error flag
bauplan table import --name events --search-uri s3://bucket/events/*.parquet --continue-on-error

# Import in best-effort mode (ignore new columns)
bauplan table import --name products --search-uri s3://bucket/products/*.parquet --best-effort

# Import in background
bauplan table import --name logs --search-uri s3://bucket/logs/*.parquet --detach

table revert

Revert a table to a previous state from a source ref.

Usage:

bauplan table revert [flags] TABLE_NAME

Flags:

Flag	Short	Type	Default	Description
`--source-ref`	`-s`	string	-	The ref (branch or tag) to revert the table from (required)
`--into-branch`	`-i`	string	-	The branch to revert the table into (defaults to active branch)
`--replace`	-	boolean	false	Replace the destination table if it exists
`--commit-body`	-	string	-	Optional commit body to append to the commit message
`--commit-property`	-	string (repeatable)	-	Commit properties as key=value pairs
`--help`	`-h`	-	-	Show help

Examples:

# Revert table from another branch
bauplan table revert customers --source-ref main

# Revert table to active branch
bauplan table revert customers --source-ref main --into-branch username.dev_branch

# Revert and replace if exists
bauplan table revert customers --source-ref v1.0 --replace

# Revert with commit message
bauplan table revert customers --source-ref main --commit-body "Reverted due to data issue"

parameter

Manage project parameters.

Usage:

bauplan parameter <command> [flags]

Available Subcommands:

ls, list - List all parameters in a project
rm, delete - Remove a parameter from a project
set - Set a parameter value in a project

parameter ls / parameter list

List all parameters in a project.

Usage:

bauplan parameter ls [flags]

Flags:

Flag	Short	Type	Default	Description
`--project-dir`	`-p`	string	"."	Path to the root Bauplan project directory
`--help`	`-h`	-	-	Show help

Examples:

# List parameters in current directory
bauplan parameter ls

# List parameters in specific project directory
bauplan parameter ls --project-dir /path/to/project

parameter rm / parameter delete

Remove a parameter from a project.

Usage:

bauplan parameter rm [flags]

Flags:

Flag	Short	Type	Default	Description
`--name`	-	string	-	Name of the parameter to remove (required)
`--project-dir`	`-p`	string	"."	Path to the root Bauplan project directory
`--help`	`-h`	-	-	Show help

Examples:

# Remove parameter from current project
bauplan parameter rm --name db_connection

# Remove parameter from specific project
bauplan parameter rm --name api_key --project-dir /path/to/project

parameter set

Set a parameter value in a project.

Usage:

bauplan parameter set [flags]

Flags:

Flag	Short	Type	Default	Description
`--name`	-	string	-	Name of the parameter to set (required)
`--type`	-	string	-	Type of the parameter [int, float, bool, str, secret]
`--value`	-	string	-	Value of the parameter to set
`--description`	-	string	-	Description of the parameter to set
`--required`	-	boolean	false	Mark the parameter as required
`--optional`	-	boolean	false	Mark the parameter as not required
`--file`	`-f`	string	-	Read value from file
`--project-dir`	`-p`	string	"."	Path to the root Bauplan project directory
`--help`	`-h`	-	-	Show help

Examples:

# Set string parameter
bauplan parameter set --name env --type str --value production

# Set integer parameter
bauplan parameter set --name max_rows --type int --value 1000

# Set boolean parameter
bauplan parameter set --name debug --type bool --value true

# Set secret parameter
bauplan parameter set --name api_key --type secret --value mysecretkey --required

# Set parameter from file
bauplan parameter set --name config --type str --file config.json

# Set parameter with description
bauplan parameter set --name db_host --type str --value "localhost" --description "Database host"

config

Configure Bauplan CLI settings.

Usage:

bauplan config <command> [flags]

Available Subcommands:

set - Set a configuration value
get - Get the current configuration

config set

Set a configuration value.

Usage:

bauplan config set [flags] <NAME> <VALUE>

Flags:

-help, -h - Show help

Examples:

# Set configuration value
bauplan config set profile_name value

config get

Get the current configuration.

Usage:

bauplan config get [flags] <NAME>

Flags:

Flag	Short	Type	Default	Description
`--all`	`-a`	boolean	false	Show all available profiles
`--help`	`-h`	-	-	Show help

Examples:

# Get specific configuration
bauplan config get profile_name

# Get all profiles
bauplan config get --all

job

Manage jobs.

Usage:

bauplan job <command> [flags]

Available Subcommands:

ls, list - List all available jobs
get - Get information about a job
logs - Get logs for a job
stop - Stop a job

job ls / job list

List all available jobs.

Usage:

bauplan job ls [flags]

Flags:

Flag	Short	Type	Default	Description
`--all-users`	-	boolean	false	Show jobs from all users, not just your own
`--id`	`-i`	string (repeatable)	-	Filter by job ID (can be specified multiple times)
`--user`	`-u`	string (repeatable)	-	Filter by username (can be specified multiple times)
`--kind`	`-k`	string (repeatable)	-	Filter by job kind: run, query, import-plan-create, import-plan-apply, table-plan-create, table-plan-apply, table-import
`--status`	`-s`	string (repeatable)	-	Filter by status: not-started, running, complete, abort, fail
`--created-after`	-	string	-	Filter jobs created after this date (e.g., 2024-01-15 or 2024-01-15T10:30:00Z)
`--created-before`	-	string	-	Filter jobs created before this date (e.g., 2024-01-15 or 2024-01-15T23:59:59Z)
`--limit` / `--max-count`	`-n`	int	10	Maximum number of jobs to return (max: 500)
`--utc`	`-z`	boolean	false	Use UTC for date parsing and display
`--help`	`-h`	-	-	Show help

Examples:

# List recent jobs for current user
bauplan job ls

# List more jobs
bauplan job ls --limit 20

# List all jobs from all users
bauplan job ls --all-users --limit 50

# Filter by status
bauplan job ls --status running

# Filter by job kind
bauplan job ls --kind run --kind query

# Filter by specific user
bauplan job ls --user username

# Filter by date range
bauplan job ls --created-after 2024-01-01 --created-before 2024-01-31

# Filter by job ID
bauplan job ls --id abc123 --id def456

# Filter failed jobs
bauplan job ls --status fail --limit 10

job get

Get information about a job.

Usage:

bauplan job get [flags] <JOB_ID>

Flags:

-help, -h - Show help

Examples:

# Get job details
bauplan job get abc123def456

job logs

Get logs for a job.

Usage:

bauplan job logs [flags] <JOB_ID>

Flags:

Flag	Type	Default	Description
`--system`	boolean	false	Include system logs
`--all`	boolean	false	Include all logs
`--help, -h`	-	-	Show help

Examples:

# Get job logs
bauplan job logs abc123def456

# Get all logs including system logs
bauplan job logs abc123def456 --all --system

job stop

Stop a job.

Usage:

bauplan job stop [flags] <JOB_ID>

Flags:

-help, -h - Show help

Examples:

# Stop a running job
bauplan job stop abc123def456

Common Workflows

Branch and Version Control

# Create a development branch
bauplan branch create username.dev_feature

# Switch to the branch
bauplan checkout username.dev_feature

# View branch information
bauplan branch get username.dev_feature

# See commits on branch
bauplan commit --limit 5

# Merge back to main (must be on main first)
bauplan checkout main
bauplan branch merge username.dev_feature

# Clean up
bauplan branch rm username.dev_feature

Data Exploration

# List namespaces
bauplan namespace ls

# List tables in a namespace
bauplan table ls --namespace raw_data

# Get table schema
bauplan table get raw_data.customers

# Run exploratory query
bauplan query "SELECT * FROM raw_data.customers LIMIT 100"

# View more rows
bauplan query --all-rows "SELECT * FROM raw_data.customers"

Pipeline Execution

# Dry run pipeline
bauplan run --dry-run

# Run pipeline with preview
bauplan run --preview head

# Run with custom parameters
bauplan run --param env=prod --param batch_size=1000

# Run in background
bauplan run --detach

# Run on specific branch
bauplan run --ref main

# Run with strict mode
bauplan run --strict

Job Management

# List recent jobs
bauplan job ls --limit 20

# List running jobs
bauplan job ls --status running

# Get job details
bauplan job get abc123

# View job logs
bauplan job logs abc123

# Stop running job
bauplan job stop abc123

# Filter jobs by date
bauplan job ls --created-after 2024-01-01 --status fail

Table Operations

# Create table from S3
bauplan table create --name customers --search-uri s3://bucket/customers/*.parquet --namespace raw_data

# Create plan before applying
bauplan table create-plan --name orders --search-uri s3://bucket/orders/*.parquet --save-plan plan.json

# Apply the plan
bauplan table create-plan-apply --plan plan.json

# Import additional data
bauplan table import --name customers --search-uri s3://bucket/customers/new/*.parquet

# Revert table
bauplan table revert customers --source-ref main

# Drop table
bauplan table rm old_table

Global Flags​

Top-Level Commands​

Command Reference​

version​

run​

rerun​

checkout​

query​

commit​

info​

branch​

branch ls / branch list​

branch create​

branch rm / branch delete​

branch get​

branch checkout​

branch diff​

branch merge​

branch rename​

tag​

tag ls / tag list​

tag create​

tag rm / tag delete​

tag rename​

namespace​

namespace ls / namespace list​

namespace create​

namespace rm / namespace delete / namespace drop​

table​

table ls / table list​

table get​

table rm / table delete / table drop​

table create​

table create-plan​

table create-plan-apply​

table create-external​

table import​

table revert​

parameter​

parameter ls / parameter list​

parameter rm / parameter delete​

parameter set​

config​

config set​

config get​

job​

job ls / job list​

job get​

job logs​

job stop​

Common Workflows​

Branch and Version Control​

Data Exploration​

Pipeline Execution​

Job Management​

Table Operations​

Global Flags

Top-Level Commands

Command Reference

version

run

rerun

checkout

query

commit

info

branch

branch ls / branch list

branch create

branch rm / branch delete

branch get

branch checkout

branch diff

branch merge

branch rename

tag

tag ls / tag list

tag create

tag rm / tag delete

tag rename

namespace

namespace ls / namespace list

namespace create

namespace rm / namespace delete / namespace drop

table

table ls / table list

table get

table rm / table delete / table drop

table create

table create-plan

table create-plan-apply

table create-external

table import

table revert

parameter

parameter ls / parameter list

parameter rm / parameter delete

parameter set

config

config set

config get

job

job ls / job list

job get

job logs

job stop

Common Workflows

Branch and Version Control

Data Exploration

Pipeline Execution

Job Management

Table Operations