Trilogy CLI Documentation

An 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 looks like this:

Command	Purpose
trilogy init	Create a new default workspace.
trilogy database	Inspect the configured database before modeling it.
trilogy ingest	Bootstrap datasources from warehouse tables or data files.
trilogy explore	List what concepts and datasources a file exposes.
trilogy fmt	Format scripts in standard syntax.
trilogy unit	Run a script against mocked data to validate business logic.
trilogy integration	Validate a script or directory against prod data.
trilogy plan	Show the execution plan without running anything.
trilogy refresh	Detect stale derived datasources and refresh them.
trilogy run	Run a production script, directory, or inline query.
trilogy render	Render a Trilogy markdown report to HTML or PNG.
trilogy serve	Serve a directory as a model store Trilogy Studio can read.
trilogy file	Create, read, update, and delete files across backends.
trilogy public	List and fetch community models.
trilogy agent	Hand a multi-step task to an AI agent.
trilogy agent-info	Print CLI documentation for AI agents.

Global Options

These come before the subcommand, as in trilogy --debug run script.preql duckdb.

Option	Description
--version	Show version and exit.
--format [rich|json]	Output format. rich (default) renders human-friendly tables and panels; json emits newline-delimited JSON events with no formatting, at parity on information, for agents and pipelines. Overrides the TRILOGY_OUTPUT_FORMAT env var.
--debug	Enable debug mode - show tracebacks on errors.
--debug-file PATH	Write SQL debug output to the given file path. Implies --debug.

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.

Dialects and Connection Arguments

Commands that touch a database take an optional dialect argument followed by connection arguments. The dialect falls back to engine.dialect in trilogy.toml when omitted.

Dialect	Aliases	Connection arguments
duck_db	duckdb	path
sqlite	sqlite3	path
postgres		host, port, username, password, database
bigquery		project
snowflake		account, username, password, database, schema
sql_server		host, port, username, password, database
presto		host, port, username, password, catalog, schema
trino		host, port, username, password, catalog, schema
clickhouse	chdb	host, port, username, password, database, mode

Connection arguments are passed as key value pairs or key=value tokens:

trilogy run script.preql duckdb path=local.duckdb
trilogy run script.preql postgres host=localhost port=5432 username=app password=secret database=shop

Warning

A bare connection string is not accepted. trilogy run etl.preql postgres "postgresql://user:pass@host/db" fails with Connection argument '...' has no value. Pass discrete key=value pairs instead, or put them in trilogy.toml under [engine.config].

DuckDB requires no arguments at all - omit path and it runs in memory.

Executing Queries

Basic Query Execution

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

# Execute an inline query
trilogy run "select count(orders.id) as order_count;" duckdb

Inline queries use Trilogy syntax, not SQL - there is no FROM clause, because the model already knows where concepts live. Use --import to reach an existing model from an inline query:

trilogy run --import raw.orders "select orders.region, sum(orders.amount) as revenue;" duckdb

With Environment Parameters

Environment parameters pass configuration values into your scripts:

trilogy run analysis.preql duckdb --param environment=prod --param batch_size=1000

Parameters support automatic type conversion:

• true/false become booleans
• Numeric strings become integers or floats
• Other strings remain strings

Debug Mode

# Tracebacks and detailed execution information
trilogy --debug run complex_query.preql snowflake account=myaccount username=app password=secret

# Capture the generated SQL for inspection
trilogy --debug-file out.sql run complex_query.preql duckdb

Debug mode provides detailed execution information, full error tracebacks, statement-by-statement timing, and enhanced logging output.

JSON Output

For agents and pipelines, --format json emits newline-delimited JSON events instead of formatted tables, at parity on information:

trilogy --format json run report.preql duckdb

Output and Progress Tracking

When running a script you will see:

• Statement-by-statement execution tracking 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

By default only the first 25 rows of each result are displayed; the query still runs in full. Use --all-rows or --displayed-rows N on trilogy run to change that.

File vs. Inline Execution

Script files:

trilogy run script.preql duckdb

• Reads the script from a file
• Uses the file's directory as the working path
• Supports relative imports and references

Inline queries:

trilogy run "select count(orders.id) as order_count;" duckdb

• Executes the query directly
• Uses the current working directory
• Useful for quick queries and testing
• Reach existing models with --import

Documentation for AI Agents

trilogy agent-info prints an AGENTS.md-style guide covering every command, option, and the language syntax - useful as context for an AI coding assistant:

trilogy agent-info > TRILOGY_AGENTS.md