Installing the CLI

VSCode

The Malloy CLI is a command-line interface for running .malloysql and .malloy files. Use it to automate transformations, build pipelines, or compile Malloy queries to SQL.

Installation Options

Option 1: NPX (No Installation)

Run directly without installing:

npx malloy-cli --help

Option 2: Global Install via npm

npm install -g malloy-cli
malloy-cli --help

The CLI stores its own configuration separately from VS Code in ~/.config/malloy/malloy-config.json. See Configuration for the full config file format, connection type properties, environment variables, and default connections.

Migrating from an older version: If you have an existing ~/.config/malloy/config.json, the CLI will automatically migrate it to the new malloy-config.json format on first run.

Connection Commands

# List all connections
malloy-cli connections list

# Create a new connection
malloy-cli connections create <type> <name> [key=value ...]

# Update an existing connection
malloy-cli connections update <name> [key=value ...]

# Show connection details
malloy-cli connections show <name>

# Test a connection
malloy-cli connections test <name>

# Show available connection types
malloy-cli connections describe

# Show properties for a connection type
malloy-cli connections describe <type>

# Delete a connection
malloy-cli connections delete <name>

Create a Connection

Properties use the exact names from the connection type registry, passed as key=value pairs. Use malloy-cli connections describe <type> to see available properties for any connection type.

# DuckDB
malloy-cli connections create duckdb mydb databasePath=/path/to/data.db

# DuckDB with MotherDuck
malloy-cli connections create duckdb md motherDuckToken=tok123 databasePath=md:my_database

# BigQuery
malloy-cli connections create bigquery bq projectId=my-project location=US

# Snowflake
malloy-cli connections create snowflake sf account=myorg warehouse=compute_wh

# Postgres
malloy-cli connections create postgres pg host=localhost port=5432 databaseName=mydb

Default Connections

If a connection name in your model matches a registered database type (DuckDB, BigQuery, Postgres, Snowflake, Trino, or Presto), the CLI creates one with default settings automatically. For example, duckdb.table('data.parquet') works out of the box. Some database types rely on environment variables for their defaults (e.g. SNOWFLAKE_ACCOUNT, TRINO_SERVER) — see the Configuration reference for the full list of defaults per connection type.

DuckDB Working Directory

When a DuckDB connection does not have workingDirectory set in the config, the CLI automatically resolves relative table paths (like duckdb.table('data.csv')) relative to the .malloy or .malloysql file being run. If you set workingDirectory explicitly, that value is used instead.

Basic Commands

Run Queries

Execute a query and return results:

# Run a named query from a Malloy file
malloy-cli run path/to/model.malloy --query query_name

# Run a MalloySQL file
malloy-cli run transforms.malloysql

Compile to SQL

Get the generated SQL without executing:

malloy-cli compile path/to/model.malloy --query query_name

Useful for:

Debugging query logic
Copying SQL to other tools
Understanding what Malloy generates

Build Persistent Tables

Build persistent tables defined with #@ persist in Malloy files:

# Build all .malloy files in the current directory
malloy-cli build

# Build a specific file
malloy-cli build path/to/model.malloy

# Build all files in a directory (recursive)
malloy-cli build models/

# Preview what would be built without executing
malloy-cli build --dry-run

# Force rebuild specific tables
malloy-cli build --refresh duckdb:daily_summary,duckdb:hourly_counts

See Persistence for full details on setting up persistent sources, manifests, and using them with VS Code.

Global Options

# Use a project-level config instead of the global default
malloy-cli --config . run model.malloy
malloy-cli --config /path/to/malloy-config.json build

# Get help
malloy-cli --help
malloy-cli run --help
malloy-cli compile --help
malloy-cli build --help

Next Steps

Database Support — Overview of all supported databases
Transform & Materialize — Use the CLI with MalloySQL for data transformations
Persistence — Persist sources as tables with the CLI builder
malloy-cli on GitHub