Skip to main content

Trilogy CLI Documentation

Trilogy CLI Documentation

A easy-to-use but powerful default tool for interacting with Trilogy models and scripts.

Installed by default with:

pip install pytrilogy

For prettier CLI outputs - recommended for anything with a human in the loop.

pip install pytrilogy[cli]

Overview

The Trilogy CLI helps you model, test, deploy, and execute Trilogy models and scripts.

Configuration Discovery

Most CLI commands can read project defaults from trilogy.toml. Unless you pass --config, the CLI starts from the target path and walks up parent directories until it finds the nearest trilogy.toml.

For a file input, discovery starts in the file's parent directory. For a directory input, discovery starts in that directory. For an inline query, discovery starts in the current working directory. The first config file found this way is used for that operation.

Use --config path/to/config.toml to point at a specific config file. Explicit config paths do not need to be named trilogy.toml.

See trilogy.toml Configuration for the full TOML syntax.

A typical development loop will look like this:

trilogy init: create a new default workspace.

trilogy ingest: bootstrap one or more datasources from tables in your warehouse.

trilogy refresh: automatically detect stale derived datasources and refresh them.

trilogy fmt: format scripts in standard syntax.

trilogy unit: run a script with mocked data to validate business logic and tests against duckdb instance.

trilogy integration: run validation against prod data for a script or set of scripts.

trilogy run: run a production script or set of scripts.

trilogy serve: serve a directory of files as a model store service that Trilogy Studio can read.

Commands

Global Options

  • --debug: Enable debug mode for detailed execution information

trilogy fmt

Format a Trilogy script file with proper syntax and structure.

Usage:

trilogy fmt <input_file>
trilogy fmt --debug script.trilogy

Arguments:

  • input: Path to the Trilogy script file to format (required)

Example:

trilogy fmt my_query.trilogy

The formatter will:

  • Parse the script and reformat it with consistent styling
  • Overwrite the original file with the formatted version
  • Display formatting statistics including number of statements and duration

trilogy run

Execute a Trilogy script file or inline query against a specified database.

Usage:

trilogy run <input> <dialect> [OPTIONS] [CONNECTION_ARGS...]
trilogy run --debug script.trilogy duckdb --param key=value

Arguments:

  • input: Either a path to a Trilogy script file or an inline query string (required)
  • dialect: Database dialect to use (required)

Options:

  • --param key=value: Environment parameters (can be specified multiple times)

Connection Arguments: Additional connection parameters are passed as --key value pairs specific to each dialect.

  • duckdb: DuckDB
    • db file on disk
  • snowflake: Snowflake
    • account, user, password
  • sqlserver: Microsoft SQL Server
    • user, password, host, port
  • postgres: PostgreSQL
    • user, password, host, port
  • bigquery: Google BigQuery
    • project
  • presto: Presto
    • user, password, host, port

Execute

Basic Query Execution

# Execute a script file against DuckDB
trilogy run my_script.trilogy duckdb

# Execute an inline query
trilogy run "SELECT * FROM users;" postgres --host localhost --user myuser

With Environment Parameters

# Set environment parameters for the script
trilogy run analysis.trilogy duckdb --param environment=prod --param batch_size=1000

Debug Mode

# Enable debug mode for detailed execution information
trilogy run --debug complex_query.trilogy snowflake --account myaccount

Environment Parameters

Environment parameters allow you to pass configuration values to your Trilogy scripts:

trilogy run script.trilogy duckdb --param debug_mode=true --param batch_size=500

Parameters support automatic type conversion:

  • true/false → boolean values
  • Numeric strings → integers or floats
  • Other strings → remain as strings

Output and Progress Tracking

When running a script, you will see:

  • Statement-by-statement execution tracking showing progress through multi-statement scripts
  • Execution timing for performance monitoring
  • Result tables displayed in a readable format
  • Error reporting with full tracebacks when debug mode is enabled
  • Progress bars for long-running operations with multiple statements

Debug Mode

Enable debug mode with the --debug flag for enhanced troubleshooting:

trilogy run --debug problematic_script.trilogy duckdb

Debug mode provides:

  • Detailed execution information
  • Full error tracebacks
  • Statement-by-statement timing
  • Enhanced logging output

File vs. Inline Execution

Script Files:

trilogy run script.trilogy duckdb
  • Reads script from file
  • Uses file's directory as working path
  • Supports relative imports and references

Inline Queries:

trilogy run "SELECT count(users) as user_count;" duckdb
  • Executes query directly
  • Uses current working directory
  • Useful for quick queries and testing