Malloy Documentation

The Malloy CLI is a command-line interface for running .malloysql and .malloy files. It can be used to automate transformations, build simple pipelines, or even integrate compiled Malloy SQL into other applications.


You can download the latest release of the Malloy-CLI from here.

If you have npm/npx installed, you can also run the CLI by either installing it (npm install -g malloy-cli) or using npx to run it npx malloy-cli {your command here}

Mac users

Please note that the CLI is currently not notarized (this is a work in progress). Running the CLI binary downloaded from our download link requires opening Privacy and Security MacOS settings and explicitly allowing it.


The CLI requires database credentials to function. Credentials can be added with malloy-cli connections create-{database}, where {database} is one of "bigquery", "postgres", or "duckdb". If you want to create a new named connection, options can be found by passing --help to any of the create-{database} commands, for example: malloy-cli connections create-bigquery --help

Setting up BigQuery if you use gCloud

gCloud is a command-line tool to work with Google Cloud. Among other things, it can store authentication information for BigQuery. If you already use gCloud to query BigQuery, setting up a connection is as simple as malloy connections create-bigquery <name> - no additional authentication information is required. Note that there are other options that you might want to set, such as billing limits - to see possible options, use malloy connections create-bigquery --help.

Default connections

By default, two connections are created if you don't already have a name that overrides them - "bigquery" and "duckdb". If .malloy`` or .malloySQL`` files reference these connections, they are created automatically. DuckDB uses a built-in instance of DuckDB, and BigQuery attempts to connect to BigQuery using any existing authentication already stored on your computer (like if you have gcloud installed).


The main commands of the CLI are run and compile - run executes queries and returns results, whereas compile returns SQL for a query or many queries.

The CLI has detailed usage information for each command. You can get general help with malloy-cli --help, and command-specific help and options with malloy-cli {command} --help