CLI Reference

CLI Reference#

The chartbook command-line interface provides tools for generating documentation and managing pipelines.

Installation#

The CLI commands require Sphinx dependencies. Choose one of these installation methods:

Recommended (isolated installation, no dependency pollution):

# Install globally via pipx
pipx install chartbook

# Or run without installing
pipx run chartbook build
uvx chartbook build

Alternative (installs dependencies in current environment):

pip install "chartbook[sphinx]"

If you run CLI commands without Sphinx dependencies installed, you’ll see a helpful error message with installation instructions.

Global Usage#

chartbook [OPTIONS] COMMAND [ARGS]...

Commands Overview#

Command

Description

build

Generate HTML documentation website

publish

Publish pipeline to a directory

create-data-glimpses

Create data glimpse reports

config

Configure the default catalog path for data loading

ls

List catalog objects (pipelines, dataframes, charts)

data

Data operations (get paths, docs)

Command Reference#

chartbook build#

Generate HTML documentation in the specified output directory.

chartbook build [OPTIONS] [OUTPUT_DIR]

Arguments:

  • OUTPUT_DIR: Directory where HTML will be generated (default: ./docs)

Options:

  • -f, --force-write: Overwrite existing output directory

  • --project-dir PATH: Path to project directory

  • --publish-dir PATH: Directory for published files (default: ./_output/to_be_published/)

  • --docs-build-dir PATH: Build directory (default: ./_docs)

  • --temp-docs-src-dir PATH: Temporary source directory (default: ./_docs_src)

  • --keep-build-dirs: Keep temporary build directories after generation

  • --size-threshold FLOAT: File size threshold in MB above which to use memory-efficient loading (default: 50)

Examples:

# Basic usage
chartbook build

# Force overwrite existing docs
chartbook build -f

# Generate in custom directory
chartbook build ./my-docs --force-write

# Keep build directories for debugging
chartbook build --keep-build-dirs

chartbook publish#

Publish the documentation to a specified directory.

chartbook publish [OPTIONS]

Options:

  • --publish-dir PATH: Directory where files will be published

  • --project-dir PATH: Path to project directory

  • -v, --verbose: Enable verbose output

Examples:

# Publish to default location
chartbook publish

# Publish to custom directory
chartbook publish --publish-dir /path/to/publish

# Publish with verbose output
chartbook publish -v

chartbook create-data-glimpses#

Create a comprehensive data glimpse report from dodo.py tasks.

chartbook create-data-glimpses [OPTIONS]

Options:

  • --no-samples: Exclude sample values from report

  • --no-stats: Exclude numeric statistics from report

  • -o, --output-dir PATH: Directory to save output file (default: current directory)

  • --size-threshold FLOAT: File size threshold in MB above which to use memory-efficient loading (default: 50)

Examples:

# Basic usage (creates data_glimpses.md)
chartbook create-data-glimpses

# Exclude sample values
chartbook create-data-glimpses --no-samples

# Exclude both samples and statistics
chartbook create-data-glimpses --no-samples --no-stats

# Save to specific directory
chartbook create-data-glimpses -o ./docs/

# Or using long form
chartbook create-data-glimpses --output-dir ./reports/

# Use a larger threshold for memory-efficient loading (100 MB)
chartbook create-data-glimpses --size-threshold 100

The report includes:

  • Summary of datasets organized by task

  • File metadata (size, type, shape)

  • Column information with data types and null percentages

  • Sample values (first 5 rows)

  • Numeric column statistics (min, max, mean, median)

For large files (above the size threshold), the command uses memory-efficient loading by only collecting sampled data while still reporting the correct total row count.

chartbook config#

Configure the default catalog path for data loading. Sets the path to a catalog’s chartbook.toml in ~/.chartbook/settings.toml so that data.load() can locate pipelines without an explicit catalog_path argument.

chartbook config

The command will:

  1. Show the current catalog path if one is already configured

  2. Prompt for the path to a catalog chartbook.toml (or its parent directory)

  3. Validate the path exists and is a catalog-type manifest

  4. Write the setting to ~/.chartbook/settings.toml

Example session:

$ chartbook config
Path to catalog chartbook.toml (or its parent directory): /data/my-catalog
Catalog path set to: /data/my-catalog/chartbook.toml

You can now load data with:
  from chartbook import data
  df = data.load(pipeline="my_pipeline", dataframe="my_df")

chartbook ls#

List catalog objects (pipelines, dataframes, charts). Without a subcommand, displays all objects in a tree format.

chartbook ls [OPTIONS] [COMMAND]

Options:

  • --catalog PATH: Path to catalog chartbook.toml (uses configured default if not specified)

Subcommands:

  • pipelines: List pipelines only

  • dataframes: List all dataframes across pipelines

  • charts: List all charts across pipelines

Examples:

# List all objects in tree format
chartbook ls

# List pipelines only
chartbook ls pipelines

# List all dataframes
chartbook ls dataframes

# List all charts
chartbook ls charts

# Use a specific catalog
chartbook ls --catalog /path/to/chartbook.toml

Example output:

$ chartbook ls
Catalog: /data/my-catalog/chartbook.toml

[pipeline] yield_curve: Yield Curve Analysis
  [dataframe] yield_curve/repo_public: Repo Public Data
  [dataframe] yield_curve/treasury_rates: Treasury Rates
  [chart] yield_curve/yield_spread: Yield Spread Chart
[pipeline] macro_data: Macro Economic Data
  [dataframe] macro_data/gdp_quarterly: GDP Quarterly

chartbook data#

Data operations for retrieving paths and documentation for dataframes.

chartbook data COMMAND [OPTIONS]

Subcommands:

chartbook data get-path#

Get the path to a dataframe’s parquet file.

chartbook data get-path --pipeline PIPELINE --dataframe DATAFRAME [--catalog PATH]

Options:

  • --pipeline: Pipeline ID (required)

  • --dataframe: Dataframe ID (required)

  • --catalog PATH: Path to catalog chartbook.toml

chartbook data get-docs#

Print documentation content for a dataframe.

chartbook data get-docs --pipeline PIPELINE --dataframe DATAFRAME [--catalog PATH]

Options:

  • --pipeline: Pipeline ID (required)

  • --dataframe: Dataframe ID (required)

  • --catalog PATH: Path to catalog chartbook.toml

chartbook data get-docs-path#

Get the path to a dataframe’s documentation source file.

chartbook data get-docs-path --pipeline PIPELINE --dataframe DATAFRAME [--catalog PATH]

Options:

  • --pipeline: Pipeline ID (required)

  • --dataframe: Dataframe ID (required)

  • --catalog PATH: Path to catalog chartbook.toml

Examples:

# Get path to a dataframe's parquet file
chartbook data get-path --pipeline yield_curve --dataframe repo_public
# Output: /data/my-catalog/yield_curve/_output/repo_public.parquet

# Print documentation for a dataframe
chartbook data get-docs --pipeline yield_curve --dataframe repo_public

# Get path to documentation source
chartbook data get-docs-path --pipeline yield_curve --dataframe repo_public
# Output: /data/my-catalog/yield_curve/docs_src/dataframes/repo_public.md

# Use a specific catalog
chartbook data get-path --pipeline macro_data --dataframe gdp_quarterly --catalog /path/to/chartbook.toml

Environment Variables#

chartbook uses several environment variables for configuration:

Variable

Description

OS_TYPE

Operating system type (windows or nix)

BASE_DIR

Base directory for the project

DATA_DIR

Directory for data files

OUTPUT_DIR

Directory for output files

Configuration File#

chartbook looks for a chartbook.toml file in the project directory. See the Configuration Guide guide for details.

Exit Codes#

  • 0: Success

  • 1: General error

  • 2: Configuration error

  • 3: File not found

Common Workflows#

Documentation Generation Workflow#

# 1. Generate data (using your own scripts/doit)
doit

# 2. Generate documentation
chartbook build -f

# 3. Publish to production
chartbook publish

Development Workflow#

# 1. Create data glimpse report
chartbook create-data-glimpses -o ./docs/

# 2. Generate docs with build dirs kept
chartbook build --keep-build-dirs

# 3. Test locally
python -m http.server -d ./docs
Contents