CLI reference

All Queria CLI commands and options

Global options

Output options (shared by list / search / info / schema / columns / summarize / sql)

The extension decides what --out writes. Passing a --format that contradicts it (say --format json --out result.csv) is an error; a matching one (--format json --out result.json) is fine.

DuckDB writes .csv and .parquet itself, so a result larger than memory still lands on disk. .json and .jsonl go through the same rendering as stdout, so --out result.json and --format json > result.json produce the same content.

table never truncates a value. Anything too wide for its column is folded onto further lines.

Folding to the terminal width is there for people to read, so it happens only when the output is displayed in a terminal (or when COLUMNS asks for a width). Piped or redirected output stays on one line per row.

Environment variables

The shape of an error under QUERIA_ERROR_FORMAT=json:

{"error": {"message": "No dataset named 'zipcodes' in the catalog. ...", "command": "info"}}

queria list

Lists all published datasets.

queria list [--format FMT] [--out PATH]

The handle column names the account that published each dataset, and datasource is the dataset name — what you write as <datasource>.<schema>.<table> in a query. Names are unique per account, so two accounts can publish the same one and the handle is what tells them apart.

queria search

Keyword search across datasets, tables, and columns (case-insensitive substring match). Datasets match on title and description; tables and columns match on name, title, and description.

Whitespace narrows. Only entries containing every word come back, and the words may sit in different places.

queria search population              # broad
queria search population small area   # only entries with all three

You can also search by the columns a table holds. --column asks for a matching column per condition, so repeating it finds tables that hold all of them. With any column condition, key or location filter, the keyword may be left out.

queria search --column 町丁目 --column 人口    # tables with a town block column and a population column
queria search park --key city --geo           # among tables keyed by municipality and holding a location

queria search [<keyword>] [--column TEXT ...] [--key ENTITY ...] [--geo] [--type {dataset,table,column}] [--limit N] [--format FMT] [--out PATH]

Without a keyword, no column entries come back: you get the matching tables and their datasets.

queria info

Shows a dataset’s metadata (license, source URL, repository, schema list, updated-at, and so on) as two columns, field / value. Fields whose value is NULL are omitted.

queria info <dataset> [--format FMT] [--out PATH]

<dataset> takes either a dataset name (e_stat) or one qualified with the account (queria/e_stat), and the handle field says which account the name landed on. The same goes for schema and columns.

queria schema

Lists a dataset’s tables and views.

queria schema <dataset> [--format FMT] [--out PATH]

queria columns

Lists a dataset’s columns. Give a table name to narrow down.

queria columns <dataset> [table] [--format FMT] [--out PATH]

queria summarize

Shows column statistics for a table (counts, min/max, NULL rate, approximate unique counts, and so on — DuckDB’s SUMMARIZE). It scans the whole table, so large tables take time and bandwidth.

queria summarize <dataset>.<schema>.<table> [--format FMT] [--out PATH]

<dataset>.<table> without a schema is interpreted as the main schema.

queria sql

Runs SQL. Datasets referenced as <dataset>.<schema>.<table> are attached automatically.

queria sql "<query>" [--datasets DS1,DS2] [--format FMT] [--out PATH]
queria sql -f PATH [--datasets DS1,DS2] [--format FMT] [--out PATH]

The query comes from exactly one of: the argument, a file, or stdin. Passing - as the argument also reads stdin. For long or generated SQL, a file or stdin saves you from shell quoting (" and $ inside the SQL).

queria sql -f query.sql
echo "SELECT 1" | queria sql -

Only statements starting with SELECT / WITH / DESCRIBE / SHOW / PRAGMA / EXPLAIN / SUMMARIZE / VALUES / TABLE / FROM / PIVOT / UNPIVOT are accepted. The same check applies to SQL read from a file or stdin. A leading comment (-- or /* */) is skipped, so a query can say what it does on top.

One run takes one statement. Several statements separated by ; are rejected (a trailing ; is fine). To get several results at once, combine them into one query with UNION ALL, or run separate commands.

queria docs

Reads this documentation from the terminal. Use it where there is no browser, or to let an AI agent look things up.

queria docs list                            # every page
queria docs show reference/cli              # one page as Markdown
queria docs show reference/cli --lang ja

Options for list:

Options for show:

list returns name / section / title / description. The name is exactly what show takes. Use --format json to read it from a program.

queria docs list --format json | jq -r '.[].name'

The name show takes is the page’s path on docs.queria.io, such as reference/cli. A leading /, a trailing .md, an en/ prefix, and a full URL are all accepted. The site’s front page is index.

An unknown name suggests the closest matches and exits with status 1.

Pages are cached (under XDG_CACHE_HOME, by default ~/.cache/queria/docs) and read from there only when the site cannot be reached; when that happens, the time the copy was taken is written to stderr. A page that does not exist (404) is reported as such without consulting the cache.

The MCP server exposes the same pages as the list_docs and show_doc tools.

queria skills

Writes the Queria skills into the directory your agent reads skills from. No Node, and no agent-specific plugin mechanism.

queria skills list                          # every published skill
queria skills show queria                   # one skill's SKILL.md
queria skills install                       # every skill, into this project
queria skills install queria --global       # the queria skill, for every project on this machine

Naming a skill installs that one. With no name, every published skill is installed.

Options for install:

Without --agent, the files go to .agents/skills, the shared location Codex, Cursor, OpenCode, Gemini CLI and GitHub Copilot all read. A project with a .claude directory, or a machine with ~/.claude, also gets a copy in .claude/skills, because that is the only place Claude Code reads.

The agents -a accepts, and where each one gets its files:

A project install goes to the root of the Git repository, so running it from a subdirectory still writes at the top.

install returns skill / agent / path / status. The values of status:

A single blocked, occupied or symlink exits with status 1. A skill you have edited yourself never goes back without --force.

The archive is cached (under XDG_CACHE_HOME, by default ~/.cache/queria/skills) and read from there only when GitHub cannot be reached.

Restart your agent, or start a new session, to have the skills loaded.

queria login

Obtains an API token through browser approval and saves it to the config file ~/.config/queria/config.toml. Running it opens the queria.io approval page in your browser; press “Approve” and the token is saved automatically.

queria login [--no-browser]

In the flow that opens a browser automatically, the wait for approval times out after 5 minutes. If it times out, run queria login again or use --no-browser.

This command needs an interactive terminal. Both flows need a person to approve in a browser, so it exits before opening one when stdin is not a terminal rather than blocking on the wait. From CI or an AI agent, issue a token at queria.io/settings/tokens and pass it via QUERIA_TOKEN or queria auth set-token.

The token expires in 90 days. Run queria login again to renew it.

queria logout

Deletes the saved token from the config file. To revoke the token on the server side, do it at queria.io/settings/tokens.

queria logout

queria auth

Manages API tokens manually. On a personal machine, queria login is the primary method. For non-interactive environments such as CI and BI tools, issue a token (which never expires) on the API tokens page at queria.io and pass it with auth set-token or the QUERIA_TOKEN environment variable.

Tokens are resolved in the order --token → the QUERIA_TOKEN environment variable → the config file ~/.config/queria/config.toml (respects XDG_CONFIG_HOME).

queria auth set-token <token>   # save to the config file (permissions 600)
queria auth status              # show whether a token exists and its origin (flag / env / config)
queria auth clear               # remove from the config file

See Authentication for details.

queria create

Registers one of your own datasets with Queria. The container has to exist before a build can fill it.

queria create <name> [--owner HANDLE] [--public | --private]

Without --owner, the dataset belongs to the handle of the account you are logged in as, and is referred to as <handle>/<name>. If you have not chosen a handle yet, the command asks you to choose one and exits. To create it in an organization account, pass --owner <org handle> — any member can, you do not have to be an admin. When you are running with an organization service token, the default is that organization.

queria edit

Changes the visibility of one of your datasets.

queria edit <name|handle/name> --visibility {public,private}

When the same name exists in more than one of your accounts, the name alone does not say which one you mean, so the command lists the candidates and stops. Say which one as <handle>/<name>. delete behaves the same way. init, pull, run, push, expire and sync take the same form in --dataset (pull and sync also accept --handle; when both are given, --handle wins).

queria delete

Deletes one of your datasets and everything in it. It asks for confirmation first.

queria delete <name|handle/name> [--yes]

One call clears up to 10,000 objects. If it stops partway, the dataset is no longer served, but what is left in storage still counts against your quota. Carry on with queria delete <handle>/<name> — a deleted dataset is no longer listed, so the name alone can no longer find it.

queria init

Creates the working catalog this dataset is built into. Only needed the first time.

queria init [--root PATH] [--dataset NAME]

queria pull

Fetches the published catalog and leaves a working catalog to build on top of.

queria pull [--root PATH] [--dataset NAME] [--handle HANDLE]

Only the catalog is fetched. The data files stay where they are published: a build reads them from there and writes new ones alongside. This is not a way to download a dataset to read — readers attach the published catalog over HTTP.

queria run

Runs a build command with this dataset’s catalog and storage in its environment. Anything after -- works.

queria run [--root PATH] [--dataset NAME] -- <command>

It does not know how to build anything; it hands over what a build cannot work out for itself (where to write, and the credentials) and gets out of the way. Environment variables you already set are left alone. The build’s exit code is passed through.

It fails when there is no working catalog — queria init starts an empty one, queria pull fetches what is already published.

queria push

Publishes what the last build left in the dataset’s storage.

queria push [--root PATH] [--dataset NAME] [--manifest PATH] [--retention-days N] [--keep-history]

The same checks as compile run before publishing. Nothing is published when the declarations do not match the data, or when the name in dataset.yml differs from the name being pushed to.

What gets published is the catalog, dataset.json, the table previews, and the dbt artifacts (manifest.json / catalog.json / semantic_manifest.json) when target/ has them.

queria expire

Drops snapshots past the retention period, and the data files they held.

queria expire [--root PATH] [--dataset NAME] [--retention-days N]

DuckLake keeps every file a live snapshot names, so a dataset that is only built and published grows without limit. This is the only thing that makes a data file removable. push runs it before publishing unless you pass --keep-history.

queria sync

Runs pull → build → push as one command.

queria sync [--root PATH] [--dataset NAME] [--handle HANDLE] [--manifest PATH] [--retention-days N] [--keep-history] -- <command>

Pulling first is not a convenience. Starting from the state Queria has is what makes the push conditional, so two publishers do not overwrite each other. When nothing has been published yet, it starts from an empty catalog. If the build exits non-zero, nothing is published.

queria validate

Checks the declarations you write for your own dataset (dataset.yml at the repository root, and *.table.yml files anywhere) against your local data. It never talks to the network — it only reads your declarations and your data.

queria validate [--root PATH] [--ducklake PATH] [--data-path PATH] [--parquet FILE ...] [--manifest PATH] [--quiet] [--strict]

Declaring licenses is optional, but leaving them out produces a warning. --strict treats warnings as failures too, which suits CI.

queria compile

Runs the same checks as validate, then writes dataset.json — the file Queria reads to list your data in the catalog. The options are the same as validate, plus an output path.

queria compile [-o PATH] [--root PATH] [--ducklake PATH] [--data-path PATH] [--parquet FILE ...] [--manifest PATH] [--quiet] [--strict]

Column names, types, column order, and nullability are read from your data rather than from the declarations, so you do not write types in the declarations.

queria export

Converts the dataset.json that compile wrote into another catalog’s format. It reads only dataset.json, not your data.

queria export --format dcat-goj [-i PATH] [-o PATH]

dcat-goj writes JSON-LD in the DCAT vocabulary that DCAT-GoJ, the Japanese government’s metadata standard, is built on. title_kana, issued, the publisher role, spatial_coverage and the rest map to DCAT-GoJ items. Items missing from dataset.json are left out of the output rather than guessed.

queria mcp

Starts the stdio MCP server. Requires the mcp extra (see MCP server).

queria [--storage-url URL] mcp

queria telemetry

Manages anonymous usage telemetry. See Telemetry for details.

queria telemetry status         # show the current state
queria telemetry disable        # opt out (saved to the config file)
queria telemetry enable         # re-enable

The environment variables DO_NOT_TRACK=1 and QUERIA_NO_TELEMETRY=1 also disable it.

queria feedback

Sends a dataset request, a data defect, or a documentation error to Queria. See Telemetry for details.

queria feedback send MESSAGE [--kind KIND] [--dataset DATASET] [--yes]
queria feedback status          # show the current setting and your client id
queria feedback allow [--auto]  # let AI agents send on your behalf
queria feedback disallow        # revoke that permission

Options for send:

Before sending, the exact payload is printed and you are asked to confirm. Outside a terminal (no TTY), running without --yes exits without sending, because the prompt cannot be answered.

The message may be up to 4000 characters. Anything longer is refused, not truncated. Sending is also refused if the message contains your configured API token, a string starting with qk_, or a known AWS access-key pattern.

allow / disallow control whether AI agents may send for you. You do not need any permission to run queria feedback send yourself. With --auto, agents may send without asking for approval each time.