# CLI

Everything sqldash does is available from the command line, which makes it easy to use
in scripts, in CI, and from coding agents that run shell commands. Every `list` and
`show` command takes `--json`, and query commands take `-f json`.

The first half of this page groups the commands by task. The [reference](#reference)
below it lists every command, argument, and option, generated from sqldash itself.
Agents can read the whole documentation as plain text at
[/llms-full.txt](/llms-full.txt), or any single page as markdown, such as
[/docs/cli.md](/docs/cli.md).

## Project

```bash
sqldash init [dir] [--demo]          # create .sqldash/; --demo adds a sample dashboard, metrics, and agent
sqldash setup [dir]                  # connect a warehouse: write a profile and the project source, then test it
sqldash serve [path | git-url]       # serve a directory, a single file, a git URL, or the workspace
sqldash lint [path] [--strict]       # validate dashboards, metrics, and agents with CI-friendly exit codes
```

`serve` takes `--port` (default 8400), `--host`, `--no-browser`, `-b BRANCH` for git
URLs, `--all` for every registered repo, and `--no-studio`. `lint --strict` also
probes SQL tools against the warehouse and fails on warnings.

## AI Studio

```bash
sqldash studio list                  # discovered agents and saved entrypoints
sqldash studio add "Codex, can edit" -- codex exec --skip-git-repo-check --sandbox workspace-write '{prompt}'
sqldash studio check "Custom agent"  # check the command resolves, without running it
```

See [AI Studio](/docs/studio/).

## Metrics and queries

```bash
sqldash metric list                               # the semantic layer at a glance
sqldash metric show revenue                       # full definition
sqldash metric query revenue -d region -g month   # evaluate a governed metric
sqldash metric query revenue --start -30d --end today --compare previous_period
sqldash query dash.yaml daily_revenue -p region=eu -f csv   # run a dashboard query headlessly
```

`-d` groups by a dimension, `-g` sets the grain, `-p` filters (`dimension=value` for
metrics, `name=value` for query parameters), and `--start` and `--end` take ISO dates
or tokens such as `-30d`, `mtd`, and `ytd`. Output is `table`, `csv`, or `json`.

## Agents

```bash
sqldash agent list                          # the agents served over MCP
sqldash agent show finance_analyst --prompt # exactly what a host receives
sqldash agent eval finance_analyst          # static checks
sqldash agent eval finance_analyst --runner 'codex exec ...'  # answer and grade each eval
```

See [Agents and evaluations](/docs/agents/).

## Introspection

```bash
sqldash dashboard list               # every dashboard: title, source, tiles, metrics used
sqldash dashboard show orders        # one dashboard in full: filters, tiles, queries
sqldash source list                  # every source, credentials redacted
sqldash source test                  # connect and SELECT 1 on each, report latency
sqldash source describe              # tables and columns
```

`dashboard show --json` is usually all the context an agent needs before editing a file.

## Workspace and MCP

```bash
sqldash repo add URL | PATH          # register a repo
sqldash repo list
sqldash repo remove NAME
sqldash mcp [path | git-url | --all] # serve the semantic layer to agents over stdio
```

See [Workspaces](/docs/workspaces/) and [MCP](/docs/mcp/).

## Share and convert

```bash
sqldash snapshot [path] -o out                  # static PNGs plus an index.html gallery
sqldash export context                          # agent-readable markdown for AGENTS.md or CLAUDE.md
sqldash export lookml | cortex                  # the semantic layer as LookML or a Snowflake semantic view
sqldash export cortex-agent finance_analyst     # a Cortex Agent and its scoped semantic view
sqldash import lookml views/ | cortex view.yaml # existing definitions into metrics.yaml
```

See [Snapshots](/docs/snapshots/) and [LookML & Cortex](/docs/lookml-cortex/).

<!-- REFERENCE:START -->

## Reference

Every command, argument, and option, generated from sqldash itself. `sqldash <command> --help` prints the same information.

### sqldash agent eval

Run an agent's evals, static checks, then (with --runner) each question answered by the runner and graded against the result sqldash computes itself. Exit 1 when any case fails.

```bash
sqldash agent eval NAME [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `NAME` | argument, required | Agent name. |
| `--target`, `-t` | option | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--runner` | option | Shell command that answers a question, e.g. 'claude -p --append-system-prompt "$(cat $SQLDASH_AGENT_PROMPT_FILE)"'. The question is appended as its last argument and piped to stdin. Without it only the static checks run. |
| `--timeout` | option | Seconds per question. Default `300.0`. |
| `--json` | flag | Print JSON instead of a table. |

### sqldash agent list

List every agent in agents.yaml.

```bash
sqldash agent list [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--json` | flag | Print JSON instead of a table. |

### sqldash agent show

Full definition of one agent, including the prompt a host receives.

```bash
sqldash agent show NAME [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `NAME` | argument, required | Agent name. |
| `--target`, `-t` | option | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--json` | flag | Print JSON instead of a table. |
| `--prompt` | flag | Print only the rendered MCP prompt. |

### sqldash dashboard list

List every dashboard in the project.

```bash
sqldash dashboard list [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--json` | flag | Print JSON instead of a table. |

### sqldash dashboard show

Full detail for one dashboard, source, filters, tiles, queries.

```bash
sqldash dashboard show NAME [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `NAME` | argument, required | Dashboard name. |
| `--target`, `-t` | option | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--json` | flag | Print JSON instead of a table. |

### sqldash export context

Generate agent-readable markdown (for CLAUDE.md / llms.txt) describing the project's metrics, dashboards, and how to query them.

```bash
sqldash export context [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--out`, `-o` | option | Write to a file instead of stdout. |
| `--branch`, `-b` | option | Branch to check out, for git URLs. |

### sqldash export cortex

Export the semantic layer as a Snowflake semantic-view YAML for Cortex Analyst. Feed the output to SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML.

```bash
sqldash export cortex [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--out`, `-o` | option | Write to a file instead of stdout. |
| `--name` | option | Semantic view name (default: project dir name) |
| `--description` | option | Description written into the exported view. |
| `--branch`, `-b` | option | Branch to check out, for git URLs. |

### sqldash export cortex-agent

Export a Cortex Agent and its semantic view. Generates files; never deploys.

```bash
sqldash export cortex-agent AGENT [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `AGENT` | argument, required | Agent name from agents.yaml. |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--out`, `-o` | option | Write to a file instead of stdout. |
| `--schema` | option | Destination DATABASE.SCHEMA. |
| `--model` | option | Cortex orchestration model. Default `auto`. |
| `--spec-only` | flag | Emit agent YAML instead of SQL. |
| `--view-out` | option | Also write the scoped semantic-view YAML. |
| `--branch`, `-b` | option | Branch to check out, for git URLs. |

### sqldash export lookml

Export the semantic layer as LookML views. Derived, cumulative, window, and non-Looker-aggregate metrics emit a plain measure and a warning, LookML cannot keep those semantics.

```bash
sqldash export lookml [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--out`, `-o` | option | Write to a file instead of stdout. |
| `--branch`, `-b` | option | Branch to check out, for git URLs. |

### sqldash import cortex

Convert a Snowflake semantic view into a sqldash metrics.yaml.

```bash
sqldash import cortex FILE [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `FILE` | argument, required | Snowflake semantic-view YAML file. |
| `--out`, `-o` | option | Write metrics.yaml here instead of stdout. |

### sqldash import lookml

Convert LookML views/measures into a sqldash metrics.yaml.

```bash
sqldash import lookml PATH [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `PATH` | argument, required | A .lkml view file or a directory of them. |
| `--out`, `-o` | option | Write metrics.yaml here instead of stdout. |

### sqldash init

Initialize a project, creates .sqldash/. Pass --demo for the sample dashboard.

```bash
sqldash init [DIRECTORY] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `DIRECTORY` | argument | Repo or directory to initialize (dashboards land in .sqldash/) Default `.`. |
| `--demo` | flag | Scaffold the sample dashboard, metrics, and orders CSV. |
| `--force` | flag | With --demo, overwrite existing demo.yaml / metrics.yaml. |

### sqldash lint

Validate dashboards and the semantic layer; designed for CI.

```bash
sqldash lint [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--strict` | flag | Probe sql tools and metrics against the warehouse; also exit non-zero on warnings. |
| `--branch`, `-b` | option | Branch to check out, for git URLs. |

### sqldash mcp

Serve the semantic layer to agents over MCP (stdio).

```bash
sqldash mcp [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | A dashboards/metrics dir, a dashboard .yaml, or a git URL. Default `.`. |
| `--allow-sql` | flag | Expose a raw run_sql tool. A keyword check refuses writing statements and only returned rows are capped; the credential's grants are the real guardrail. |
| `--row-limit` | option | Max rows returned per tool call. Default `1000`. |
| `--branch`, `-b` | option | Branch to check out (git URLs only) |
| `--all` | flag | Serve every repo registered with 'sqldash repo add' (metrics namespaced repo/name) |

### sqldash metric list

List every metric in the semantic layer.

```bash
sqldash metric list [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--json` | flag | Print JSON instead of a table. |

### sqldash metric query

Evaluate a metric, group by dimensions and/or a time grain, filter by values.

```bash
sqldash metric query NAME [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `NAME` | argument, required | Metric name. |
| `--target`, `-t` | option | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--dimension`, `-d` | option | Dimension to group by. Repeatable. |
| `--grain`, `-g` | option | Time grain, one of hour, day, week, month, quarter, or year. |
| `--param`, `-p` | option | Filter as dimension=value. |
| `--start` | option | ISO date, or a token: -30d, last_30_days, mtd, ytd, today. |
| `--end` | option | ISO date. A token here means today, a window ends now. |
| `--format`, `-f` | option | table \| csv \| json. Default `table`. |
| `--dashboard` | option | Resolve inline metrics in this dashboard's scope and apply its filter defaults. |
| `--compare` | option | previous_period \| yoy: second window + delta, matching the tile. Needs both --start and --end, or a --dashboard daterange default. |
| `--row-limit` | option | Max rows returned. Default `1000`. |

### sqldash metric show

Full definition of one metric.

```bash
sqldash metric show NAME [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `NAME` | argument, required | Metric name. |
| `--target`, `-t` | option | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--dashboard` | option | Resolve inline metrics in this dashboard's scope. |
| `--json` | flag | Print JSON instead of a table. |

### sqldash query

Run a dashboard query or a semantic-layer metric headlessly (for scripts and CI).

```bash
sqldash query TARGET NAME [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument, required | Dashboard .yaml, a project dir, or a git URL. |
| `NAME` | argument, required | A query or metric name (use dashboard.query to disambiguate) |
| `--dashboard` | option | Dashboard to resolve the query in. |
| `--param`, `-p` | option | Parameter as name=value (repeatable) |
| `--dimension`, `-d` | option | Metric dimension to group by (repeatable) |
| `--grain`, `-g` | option | Metric time grain (hour\|day\|week\|month\|quarter\|year) |
| `--format`, `-f` | option | Output: table \| csv \| json. Default `table`. |
| `--source` | option | A picker key: this dashboard's sources: name, metrics.yaml, or another dashboard's other.source / other.sources.prod. |
| `--start` | option | Metric only. ISO date, or a token: -30d, last_30_days, mtd, ytd, today. |
| `--end` | option | Metric only. ISO date. A token here means today, a window ends now. |
| `--compare` | option | Metric only. previous_period \| yoy, second window + delta, matching the tile. |
| `--row-limit` | option | Max rows returned. Default `10000`. |

### sqldash repo add

Register a repo; 'sqldash serve' (no target) then serves all registered repos.

```bash
sqldash repo add TARGET [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument, required | A git URL or a local directory. |
| `--name`, `-n` | option | Registry name (default: repo basename) |
| `--branch`, `-b` | option | Branch to serve (git URLs only) |

### sqldash repo list

List registered repos.

```bash
sqldash repo list [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `--json` | flag | Print JSON instead of a table. |

### sqldash repo remove

Remove a repo from the registry (never touches the repo itself).

```bash
sqldash repo remove NAME
```

| name | kind | description |
| --- | --- | --- |
| `NAME` | argument, required | Registered repo name. |

### sqldash serve

Serve dashboards from a file, a directory, a git repo, or every registered repo.

```bash
sqldash serve [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | A dashboard .yaml file, a directory, or a git URL. Omit to serve the current directory, or, when it has no dashboards, every registered repo (see 'sqldash repo add') |
| `--port` | option | Port to listen on. Default `8400`. |
| `--host` | option | Host to bind. Default `127.0.0.1`. |
| `--branch`, `-b` | option | Branch to check out (git URLs only) |
| `--no-browser` | flag | Don't open the browser. |
| `--row-limit` | option | Max rows returned per query. Default `10000`. |
| `--all` | flag | Serve every repo registered with 'sqldash repo add'. |
| `--studio`, `--no-studio` | flag | Local coding-agent editing (enabled by default on loopback hosts) |

### sqldash setup

Write a local profile and a project source, then test the connection. Interactive with no flags. Pass --type (and the fields that type needs) to run non-interactively, passwords are always ${env:VAR} references, never literals, and they land in ~/.config/sqldash/profiles.yaml, not the repo. On a tty, missing flags are asked instead of exiting.

```bash
sqldash setup [DIRECTORY] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `DIRECTORY` | argument | Repo or directory to initialize (dashboards land in .sqldash/) Default `.`. |
| `--type` | option | duckdb \| postgres \| snowflake \| bigquery \| databricks \| mysql \| url. |
| `--profile` | option | Name written to ~/.config/sqldash/profiles.yaml. |
| `--account` | option | Snowflake account locator. |
| `--host` | option | Database host. |
| `--port` | option | Database port. |
| `--database` | option | Database name; for duckdb an existing .duckdb file (relative to the project dir) or :memory:, a file that does not exist yet needs --skip-test. |
| `--schema` | option | Schema to use. |
| `--warehouse` | option | Snowflake warehouse. |
| `--role` | option | Snowflake role. |
| `--username`, `--user` | option | Database user. |
| `--auth` | option | snowflake: externalbrowser \| password \| pat \| keypair. |
| `--password-env` | option | Env var the profile's password: ${env:VAR} will name. |
| `--token-env` | option | Env var the profile's token: ${env:VAR} will name. |
| `--private-key-path` | option | Path to a Snowflake private key, for key pair auth. |
| `--url` | option | Raw SQLAlchemy URL (use ${env:VAR} for secrets) |
| `--project` | option | BigQuery project. |
| `--http-path` | option | Databricks HTTP path. |
| `--catalog` | option | Databricks catalog. |
| `--register` | flag | Register this directory with 'sqldash repo add'. |
| `--skip-test` | flag | Don't connect after writing. |

### sqldash snapshot

Render dashboards to static PNGs + an index.html, wallboards and stakeholders without warehouse credentials. Needs the 'snapshot' extra.

```bash
sqldash snapshot [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--out`, `-o` | option | Output directory. Default `snapshots`. |
| `--dashboard`, `-d` | option | Only these dashboards (default: all) |
| `--theme` | option | dark \| light. Default `dark`. |
| `--width` | option | Viewport width in px (rendered at 2x) Default `1440`. |
| `--branch`, `-b` | option | Branch to check out (git URLs only) |
| `--all` | flag | Snapshot every repo registered with 'sqldash repo add'. |

### sqldash source describe

Tables and columns of a source, the raw material for metrics and queries.

```bash
sqldash source describe [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--only` | option | Describe one source by its listed name. |
| `--json` | flag | Print JSON instead of a table. |

### sqldash source list

List every data source in the project (credentials redacted).

```bash
sqldash source list [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--json` | flag | Print JSON instead of a table. |

### sqldash source test

Connect to each source and run SELECT 1, verifies credentials and drivers.

```bash
sqldash source test [TARGET] [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `TARGET` | argument | Project dir, dashboard .yaml, or git URL. Default `.`. |
| `--only` | option | Test just one source by its listed name. |

### sqldash studio add

Save an agent entrypoint. Use -- before command arguments.

```bash
sqldash studio add NAME COMMAND [OPTIONS]
```

| name | kind | description |
| --- | --- | --- |
| `NAME` | argument, required | Display name, e.g. Custom agent. |
| `COMMAND` | argument, required | Command and arguments; include {prompt}. |
| `--shell` | option | Absolute bash/zsh path for aliases/functions. |
| `--env` | option | Local environment override KEY=VALUE. |

### sqldash studio check

Check that an entrypoint resolves without starting the coding agent.

```bash
sqldash studio check NAME
```

| name | kind | description |
| --- | --- | --- |
| `NAME` | argument, required | Registry name. Defaults to the repo's basename. |

### sqldash studio list

List discovered and saved entrypoint names and commands (never environment values).

```bash
sqldash studio list
```

<!-- REFERENCE:END -->