Malloy Documentation
search
previousConfiguration
Querying a Semantic Modelnext

Installing the CLI

VSCode document

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

Configure Connections

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

Two connections are created automatically if you don't already have a connection that overrides them — bigquery and duckdb. If your Malloy files reference these connection names, they work without explicit setup. DuckDB uses a built-in in-memory instance, and BigQuery attempts to connect using any existing gcloud authentication on your computer.

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

Get Help 

malloy-cli --help
malloy-cli run --help
malloy-cli compile --help

Next Steps