Skip to main content

Trilogy CLI Documentation

Trilogy CLI Documentation

Simple, powerful defaul tool for interacting with Trilogy models and scripts.

Overview

The Trilogy CLI provides a command-line interface for executing Trilogy scripts and queries against supported backends.

Installation & Setup

# The CLI is typically installed as part of the trilogy package
pip install trilogy

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.

Supported Database Dialects

The CLI supports the following database systems:

  • duckdb: DuckDB database
  • snowflake: Snowflake data warehouse
  • sqlserver: Microsoft SQL Server
  • postgres: PostgreSQL database
  • bigquery: Google BigQuery
  • presto: Presto distributed SQL query engine

Usage Examples

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

Database-Specific Examples

DuckDB:

trilogy run query.trilogy duckdb --database my_db.duckdb

PostgreSQL:

trilogy run script.trilogy postgres --host localhost --port 5432 --user myuser --password mypass

Snowflake:

trilogy run analysis.trilogy snowflake --account myaccount --user myuser --warehouse mywarehouse

BigQuery:

trilogy run report.trilogy bigquery --project my-project --dataset my_dataset

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

Tips and Best Practices

  1. Use environment parameters for configurable values instead of hardcoding them in scripts
  2. Format scripts regularly to maintain consistent code style

Common Issues

Connection Problems:

  • Verify database credentials and connection parameters
  • Check network connectivity to remote databases
  • Ensure database drivers are installed

Parse Errors:

  • Use trilogy fmt to check script syntax
  • Enable debug mode for detailed error information
  • Verify Trilogy syntax in your scripts