Reference

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 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, or any single page as markdown, such as /docs/cli.md.

Project

Terminal

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

Terminal

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.

Metrics and queries

Terminal

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

Terminal

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.

Introspection

Terminal

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

Terminal

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 and MCP.

Terminal

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 and LookML & Cortex.

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.

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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).

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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).

Terminal

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

Terminal

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.

Terminal

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).

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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).

Terminal

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.

Terminal

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.

Terminal

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.

Terminal

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).

Terminal

sqldash studio list