# CLI reference

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

## Global options

  {`Name of the profile to use`}
  {`Output format`}
  {`Timeout (in seconds) for client operations (-1 = no timeout)`}
  {`Print verbose logs`}

---

## bauplan version

Print version

```sh
bauplan version
```

---

## bauplan info

Print debug information about the current environment

```sh
bauplan info
```

---

## bauplan run

Execute a bauplan run

```sh
bauplan run [OPTIONS]
```

  **Options**

    {`Path to the root Bauplan project directory`}
    {`Ref or branch name from which to run the job [default: active branch]`}
    {`Namespace to run the job in. If not set, the job will be run in the default namespace for the project`}
    {`Set the cache mode`}
    {`Set the preview mode`}
    {`Exit upon encountering runtime warnings (e.g., invalid column output)`}
    {`Run the dag as a transaction. Will create a temporary branch where models are materialized. Once all models succeed, it will be merged to the branch in which this run is happening`}
    {`Dry run the job without materializing any models`}
    {`Set a parameter for the job. Format: key=value. Can be used multiple times`}
    {`Run the job in the background instead of streaming logs`}
    {`Extra arguments as key=value pairs (repeatable)`}
    {`Set the job priority (1-10, where 10 is highest priority)`}

    ```sh
    # 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 on --preview head

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

# Run in background
bauplan run --detach
    ```

---

## bauplan branch

Manage branches

```sh
bauplan branch <COMMAND> [OPTIONS]
```

    List branches (shows only your branches by default)
    Create a new branch
    Delete a branch
    Get information about a branch
    Set the active branch
    Show the diff between the active branch and another branch
    Merge a branch into the active branch
    Rename a branch

### bauplan branch ls

List branches (shows only your branches by default)

**Aliases:** `list`

```sh
bauplan branch ls [OPTIONS] [BRANCH_NAME]
```

  **Arguments**

    ">{`Branch name`}

  **Options**

    {`Show all branches, including those from other namespaces (users)`}
    {`Filter by name`}
    {`Filter by user`}
    {`Limit the number of branches to show`}

    ```sh
    # 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
    ```

### bauplan branch create

Create a new branch

```sh
bauplan branch create [OPTIONS] <BRANCH_NAME>
```

  **Arguments**

    ">{`Branch name`}

  **Options**

    {`Ref to branch from [default: active branch]`}
    {`Do not fail if the branch already exists`}

    ```sh
    # 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 if it doesn't already exist
bauplan branch create username.my_branch --if-not-exists
    ```

### bauplan branch rm

Delete a branch

**Aliases:** `delete`

```sh
bauplan branch rm [OPTIONS] <BRANCH_NAME>
```

  **Arguments**

    ">{`Branch name`}

  **Options**

    {`Command succeeds even if the branch does not exist`}

    ```sh
    # Delete a branch
bauplan branch rm username.old_branch

# Conditionally delete
bauplan branch rm username.maybe_branch --if-exists
    ```

### bauplan branch get

Get information about a branch

```sh
bauplan branch get [OPTIONS] <BRANCH_NAME>
```

  **Arguments**

    ">{`Branch name`}

  **Options**

    {`Filter by namespace (exact match or regex)`}

    ```sh
    # Get branch information
bauplan branch get username.dev_branch

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

### bauplan branch checkout

Set the active branch

```sh
bauplan branch checkout <BRANCH_NAME>
```

  **Arguments**

    ">{`Branch name`}

    ```sh
    bauplan branch checkout main
bauplan branch checkout username.dev_branch
    ```

### bauplan branch diff

Show the diff between the active branch and another branch

```sh
bauplan branch diff [OPTIONS] <BRANCH_NAME_A> [BRANCH_NAME_B]
```

  **Arguments**

    ">{`Branch name a`}
    ">{`Branch name b`}

  **Options**

    {`Filter by namespace (exact match or regex)`}

    ```sh
    # 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
    ```

### bauplan branch merge

Merge a branch into the active branch

```sh
bauplan branch merge [OPTIONS] <BRANCH_NAME>
```

  **Arguments**

    ">{`Branch name`}

  **Options**

    {`Optional commit message`}

    ```sh
    # 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"
    ```

### bauplan branch rename

Rename a branch

```sh
bauplan branch rename <BRANCH_NAME> <NEW_BRANCH_NAME>
```

  **Arguments**

    ">{`Branch name`}
    ">{`New branch name`}

    ```sh
    bauplan branch rename username.old_name username.new_name
    ```

---

## bauplan tag

Manage tags

```sh
bauplan tag <COMMAND> [OPTIONS]
```

    List all available tags (default action)
    Create a new tag
    Delete a tag
    Rename a tag

### bauplan tag ls

List all available tags (default action)

**Aliases:** `list`

```sh
bauplan tag ls [OPTIONS]
```

  **Options**

    {`Filter by name (can be a regex)`}
    {`Limit the number of tags to show`}

    ```sh
    # List all tags
bauplan tag ls

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

# Limit results
bauplan tag ls --limit 10
    ```

### bauplan tag create

Create a new tag

```sh
bauplan tag create [OPTIONS] <TAG_NAME>
```

  **Arguments**

    ">{`Tag name`}

  **Options**

    {`Ref to create the tag from [default: active branch]`}
    {`Do not fail if the tag already exists`}

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

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

# Create tag if it doesn't already exist
bauplan tag create v1.0 --if-not-exists
    ```

### bauplan tag rm

Delete a tag

**Aliases:** `delete`

```sh
bauplan tag rm [OPTIONS] <TAG_NAME>
```

  **Arguments**

    ">{`Tag name`}

  **Options**

    {`Do not fail if the tag does not exist`}

    ```sh
    # Delete a tag
bauplan tag rm v1.0

# Conditionally delete
bauplan tag rm v1.0 --if-exists
    ```

### bauplan tag rename

Rename a tag

```sh
bauplan tag rename <TAG_NAME> <NEW_TAG_NAME>
```

  **Arguments**

    ">{`Tag name`}
    ">{`New tag name`}

    ```sh
    bauplan tag rename v1.0 v1.0-stable
    ```

---

## bauplan commit

Show commit history for a ref

```sh
bauplan commit [OPTIONS] [REF_NAME]
```

  **Arguments**

    ">{`Ref or branch name to get commits from [default: active branch]`}

  **Options**

    {`Filter by message content (string or a regex like "^something.*$")`}
    {`Filter by author username (string or a regex like "^something.*$")`}
    {`Filter by author name (string or a regex like "^something.*$")`}
    {`Filter by author email (string or a regex like "^something.*$")`}
    {`Filter by a property. Format: key=value. Can be used multiple times`}
    {`Limit the number of commits to show`}
    {`How to format commits`}

    ```sh
    # Show recent commits on active branch
bauplan commit

# Show commits from specific branch
bauplan commit main

# Show more commits
bauplan commit --max-count 20

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

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

# Show commits in oneline format
bauplan commit --format oneline
    ```

---

## bauplan namespace

Manage namespaces

```sh
bauplan namespace <COMMAND> [OPTIONS]
```

    List available namespaces
    Create a new namespace
    Drop a namespace from the data catalog

### bauplan namespace ls

List available namespaces

**Aliases:** `list`

```sh
bauplan namespace ls [OPTIONS] [NAMESPACE]
```

  **Arguments**

    ">{`Filter namespaces by name`}

  **Options**

    {`Ref or branch name to list namespaces from [default: active branch]`}
    {`Limit the number of namespaces to show`}

    ```sh
    # 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
    ```

### bauplan namespace create

Create a new namespace

```sh
bauplan namespace create [OPTIONS] <NAMESPACE>
```

  **Arguments**

    ">{`Namespace`}

  **Options**

    {`Branch to create the namespace in [default: active branch]`}
    {`Do not fail if the namespace already exists`}
    {`Optional commit body to append to the commit message`}

    ```sh
    # Create namespace on active branch
bauplan namespace create raw_data

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

# Create namespace if it doesn't already exist
bauplan namespace create my_namespace --if-not-exists
    ```

### bauplan namespace rm

Drop a namespace from the data catalog

**Aliases:** `delete`,  `drop`

```sh
bauplan namespace rm [OPTIONS] <NAMESPACE>
```

  **Arguments**

    ">{`Namespace`}

  **Options**

    {`Branch to delete the namespace from [default: active branch]`}
    {`Do not fail if the namespace does not exist`}
    {`Optional commit body to append to the commit message`}

    ```sh
    # Delete namespace from active branch
bauplan namespace rm old_namespace

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

# Conditionally delete
bauplan namespace rm maybe_namespace --if-exists
    ```

---

## bauplan table

Manage tables

```sh
bauplan table <COMMAND> [OPTIONS]
```

    List all available tables
    Get information about a table
    Drop a table from the data catalog (does not free up storage)
    Create a new table
    Create a plan for a new table
    Apply a table create plan manually
    Create an external read-only Iceberg table from existing data without any copies
    Import data to an existing table. Use `bauplan table create` to create the table first
    Revert a table to a previous state from a source ref

### bauplan table ls

List all available tables

**Aliases:** `list`

```sh
bauplan table ls [OPTIONS]
```

  **Options**

    {`Filter tables by name (exact match or regex)`}
    {`Filter by namespace (exact match or regex)`}
    {`Ref or branch name to list tables from [default: active branch]`}
    {`Limit the number of tables to show`}

    ```sh
    # 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
    ```

### bauplan table get

Get information about a table

```sh
bauplan table get [OPTIONS] <TABLE_NAME>
```

  **Arguments**

    ">{`Table name`}

  **Options**

    {`Ref or branch name to get the table from [default: active branch]`}

    ```sh
    # 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
    ```

### bauplan table rm

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

**Aliases:** `delete`,  `drop`

```sh
bauplan table rm [OPTIONS] <TABLE_NAME>
```

  **Arguments**

    ">{`Table name`}

  **Options**

    {`Branch to delete the table from [default: active branch]`}
    {`Do not fail if the table does not exist`}
    {`Optional commit body to append to the commit message`}

    ```sh
    # Delete table from active branch
bauplan table rm old_table

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

# Conditionally delete
bauplan table rm maybe_table --if-exists
    ```

### bauplan table create

Create a new table

```sh
bauplan table create [OPTIONS] <TABLE_NAME>
```

  **Arguments**

    ">{`Name of the table to create`}

  **Options**

    {`Branch to create the table in [default: active branch]`}
    {`Namespace for the table`}
    {`S3 URI pattern for parquet files to import (e.g. s3://bucket/path/*)`}
    {`Partition the table by the given columns`}
    {`Replace the existing table, if it exists`}
    {`Extra arguments as key=value pairs (repeatable)`}
    {`Set the job priority (1-10, where 10 is highest priority)`}

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

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

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

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

### bauplan table create-plan

Create a plan for a new table

```sh
bauplan table create-plan [OPTIONS] <TABLE_NAME>
```

  **Arguments**

    ">{`Name of the table to create`}

  **Options**

    {`Branch to create the table in [default: active branch]`}
    {`Namespace for the table`}
    {`S3 URI pattern for parquet files to import (e.g. s3://bucket/path/*)`}
    {`Partition the table by the given columns`}
    {`Replace the existing table, if it exists`}
    {`A filename to write the plan to`}
    {`Extra arguments as key=value pairs (repeatable)`}

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

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

### bauplan table create-plan-apply

Apply a table create plan manually

```sh
bauplan table create-plan-apply [OPTIONS]
```

  **Options**

    {`Path to a plan YAML file; reads from stdin if not provided`}
    {`Extra arguments as key=value pairs (repeatable)`}
    {`Set the job priority (1-10, where 10 is highest priority)`}

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

### bauplan table create-external

Create an external read-only Iceberg table from existing data without any copies

```sh
bauplan table create-external [OPTIONS] <TABLE_NAME>
```

  **Arguments**

    ">{`Name of the external table to create`}

  **Options**

    {`Branch to create the table in [default: active branch]`}
    {`Namespace for the table`}
    {`URI to Iceberg metadata.json file (e.g., s3://bucket/metadata.json)`}
    {`Search pattern for parquet files (e.g., s3://bucket/2025/*.parquet). Can be specified multiple times`}
    {`Overwrite the table if it already exists`}
    {`Run the job in the background (only for parquet mode)`}
    {`Extra arguments as key=value pairs, repeatable (only for parquet mode)`}
    {`Set the job priority (1-10, where 10 is highest priority) (only for parquet mode)`}

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

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

# Create external table with multiple search patterns
bauplan table create-external 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 events --search-pattern "s3://bucket/data/*.parquet" --overwrite
    ```

### bauplan table import

Import data to an existing table. Use `bauplan table create` to create the table first

```sh
bauplan table import [OPTIONS] <TABLE_NAME>
```

  **Arguments**

    ">{`Name of table where data will be imported into`}

  **Options**

    {`Branch to import into [default: active branch]`}
    {`Namespace for the table`}
    {`Uri search string e.g s3://bucket/path/a/*`}
    {`Don't fail the command even if 1/N files fails to import`}
    {`Force importing of files without checking what was already imported. This will likely result in duplicate rows being imported`}
    {`Set to ignore new columns. if an import file  has column aa, bb, and parquet has col aa, bb, cc, columns aa and bb will be imported`}
    {`Run the job in the background`}
    {`Extra arguments as key=value pairs (repeatable)`}
    {`Set the job priority (1-10, where 10 is highest priority)`}

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

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

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

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

### bauplan table revert

Revert a table to a previous state from a source ref

```sh
bauplan table revert [OPTIONS] <TABLE_NAME>
```

  **Arguments**

    ">{`Table name`}

  **Options**

    {`The ref (branch or tag) to revert the table from`}
    {`Branch to revert the table into [default: active branch]`}
    {`Replace the destination table if it exists`}
    {`Optional commit body to append to the commit message`}
    {`Commit properties as key=value pairs (can be used multiple times)`}

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

# Revert table to specific 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"
    ```

---

## bauplan query

Run an SQL query

```sh
bauplan query [OPTIONS] [SQL]
```

  **Arguments**

    ">{`SQL query. Column and table names are case-sensitive`}

  **Options**

    {`Ref or branch name to run query against [default: active branch]`}
    {`Namespace to run the query in`}
    {`Read query from file`}
    {`Set the cache mode`}
    {`Limit number of returned rows. (use --all-rows to disable this)`}
    {`Do not limit returned rows. Supersedes --max-rows`}
    {`Do not truncate output`}
    {`Extra arguments as key=value pairs (repeatable)`}
    {`Set the job priority (1-10, where 10 is highest priority)`}

    ```sh
    # 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"
    ```

---

## bauplan parameter

Manage project parameters

```sh
bauplan parameter <COMMAND> [OPTIONS]
```

    List all parameters in a project
    Remove a parameter from a project
    Set a parameter value in a project

### bauplan parameter ls

List all parameters in a project

**Aliases:** `list`

```sh
bauplan parameter ls [OPTIONS]
```

  **Options**

    {`Path to the root Bauplan project directory`}

    ```sh
    # List parameters in current directory
bauplan parameter ls

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

### bauplan parameter rm

Remove a parameter from a project

**Aliases:** `delete`

```sh
bauplan parameter rm [OPTIONS] <NAME>
```

  **Arguments**

    ">{`Name of the parameter to remove`}

  **Options**

    {`Path to the root Bauplan project directory`}

    ```sh
    # Remove parameter from current project
bauplan parameter rm db_connection

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

### bauplan parameter set

Set a parameter value in a project

```sh
bauplan parameter set [OPTIONS] <NAME> [DEFAULT_VALUE]
```

  **Arguments**

    ">{`Name`}
    ">{`A default value`}

  **Options**

    {`The type of the parameter`}
    {`A description of the parameter`}
    {`Mark the parameter as required`}
    {`Mark the parameter as optional`}
    {`Read value from file`}
    {`Path to the root Bauplan project directory`}

    ```sh
    # Set string parameter
bauplan parameter set env production --type str

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

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

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

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

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

---

## bauplan config

Configure Bauplan CLI settings

```sh
bauplan config <COMMAND> [OPTIONS]
```

    Set a configuration value
    Get the current configuration

### bauplan config set

Set a configuration value

```sh
bauplan config set <NAME> <VALUE>
```

  **Arguments**

    ">{`Setting name`}
    ">{`Value to set`}

    ```sh
    # Set configuration value
bauplan config set api_key your_key
    ```

### bauplan config get

Get the current configuration

```sh
bauplan config get [OPTIONS]
```

  **Options**

    {`Show all the available profiles`}

    ```sh
    # Show the current profile
bauplan config get

# Show all profiles
bauplan config get --all
    ```

---

## bauplan job

Manage jobs

```sh
bauplan job <COMMAND> [OPTIONS]
```

    List all available jobs
    Get information about a job
    Get logs for a job
    Stop a job

### bauplan job ls

List all available jobs

**Aliases:** `list`

```sh
bauplan job ls [OPTIONS]
```

  **Options**

    {`Show jobs from all users, not just your own`}
    {`Filter by job ID (can be specified multiple times)`}
    {`Filter by username (can be specified multiple times)`}
    {`Filter by job kind`}
    {`Filter by status`}
    {`Filter jobs created after this date (e.g., 2024-01-15 or 2024-01-15T10:30:00Z)`}
    {`Filter jobs created before this date (e.g., 2024-01-15 or 2024-01-15T23:59:59Z)`}
    {`Maximum number of jobs to return (max: 500)`}
    {`Use UTC for date parsing and display`}

    ```sh
    # List recent jobs for current user
bauplan job ls

# List more jobs
bauplan job ls --max-count 20

# List all jobs from all users
bauplan job ls --all-users --max-count 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 --max-count 10
    ```

### bauplan job get

Get information about a job

```sh
bauplan job get <JOB_ID>
```

  **Arguments**

    ">{`Job id`}

    ```sh
    # Get job details
bauplan job get abc123def456
    ```

### bauplan job logs

Get logs for a job

```sh
bauplan job logs [OPTIONS] <JOB_ID>
```

  **Arguments**

    ">{`Job id`}

  **Options**

    {`Include system logs`}
    {`Include all logs`}

    ```sh
    # Get job logs
bauplan job logs abc123def456

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

### bauplan job stop

Stop a job

```sh
bauplan job stop <JOB_ID>
```

  **Arguments**

    ">{`Job id`}

    ```sh
    # Stop a running job
bauplan job stop abc123def456
    ```

---

## bauplan checkout

Set the active branch

```sh
bauplan checkout [OPTIONS] <BRANCH_NAME>
```

  **Arguments**

    ">{`Branch name`}

  **Options**

    {`Create the branch before switching (fails if it already exists)`}
    {`Ref from which to create when using -b. If not specified, the default is the currently active branch`}

    ```sh
    # Checkout existing branch
bauplan checkout main

# Checkout user branch
bauplan checkout username.dev_branch

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

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

---

## bauplan init

Initialize a new bauplan project

```sh
bauplan init [OPTIONS] [PATH]
```

  **Arguments**

    ">{`Directory to initialize. Defaults to the current directory`}

  **Options**

    {`Project name. Defaults to the directory name`}

    ```sh
    # Initialize a new project in the current directory
bauplan init

# Initialize in a specific directory
bauplan init my_project

# Initialize with a custom project name
bauplan init --name my_pipeline
    ```