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.

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