Command-Line Interface

The Querri CLI (querri) lets you work with Querri from a terminal or a script. Upload files, run projects and chats, query sources, and manage users, API keys, access policies and sharing. Add --json and the output pipes cleanly into other tools.

What’s a CLI good for?

A CLI (command-line interface) is a program you run by typing commands in a terminal. You’d reach for the Querri CLI when you want to:

• Automate Querri: upload a file every night, rerun a project from a scheduled job, or materialize views after a load.
• Script setup: create users, access policies and API keys in one go.
• Stay in the terminal: ask a question about your data without opening the browser.
• Pipe results onward: send JSON output to jq or anything else that reads it.

If you’re building a Python application, the Python SDK is the same package, imported as a library.

Installation

The cli extra adds what the command-line tool needs (Typer, Rich and Pillow). Python 3.10 or later is required.

pip install "querri[cli]"

Check it worked:

querri --version

For the library alone, without the command-line tool:

pip install querri

Upgrading

pip install --upgrade "querri[cli]"

Sign in

The quickest way is to sign in through your browser:

querri auth login

The CLI opens your browser, you sign in to Querri as usual, and your credentials are saved to ~/.querri/tokens.json. They refresh automatically, so you normally sign in once per machine. Add --host to sign in to a different Querri server, or --organization to sign in to a specific organization.

querri auth status          # who you're signed in as, and where
querri whoami               # current user, organization and host
querri auth switch-org      # move to another organization without signing in again
querri auth logout          # sign out and revoke stored credentials

Use an API key in scripts and CI

For jobs that run without a person, use an API key. An admin creates one in Settings → API Keys. Then set:

export QUERRI_API_KEY=qk_your_api_key
export QUERRI_ORG_ID=your_org_id

The CLI picks credentials in this order:

1. The --api-key option.
2. The QUERRI_API_KEY or QUERRI_ACCESS_TOKEN environment variable. If both are set, the access token is the one sent.
3. Your stored sign-in from querri auth login.

Quick start

Upload a file, create a project, add the file, and ask a question:

querri file upload sales.csv
querri project new "Q3 Sales Analysis"
querri project add-source <file_id>
querri project chat -m "What are the top 5 products by revenue?"

project new selects the new project, so the commands after it don’t need a project ID. Switch with querri project select.

Scripting

Three global options matter most for automation:

• --json prints machine-readable JSON instead of formatted tables.
• --no-interactive never prompts; a missing value fails straight away.
• --quiet prints IDs only.

Global options go before the command:

querri --json --no-interactive file upload data.csv    # works
querri file upload data.csv --json                     # fails: the option is in the wrong place

Pipe JSON into jq to pick out IDs:

FILE_ID=$(querri --json --no-interactive file upload data.csv | jq -r .id)
PROJECT_ID=$(querri --json --no-interactive project new "Nightly" | jq -r .id)
querri --json --no-interactive --project "$PROJECT_ID" project add-source "$FILE_ID"
querri --json --no-interactive --project "$PROJECT_ID" project chat -m "Summarize the data"

Uploading several files at once (a glob) prints a JSON list, not a single object.

Global options

Option	Environment variable	What it does
--host	QUERRI_HOST	Server to talk to. Default https://app.querri.com. Include the scheme, like http://localhost.
--api-key	QUERRI_API_KEY	API key. Prefer the environment variable, because the option can end up in your shell history.
--org-id	QUERRI_ORG_ID	Organization ID, needed with an API key.
--project, -p	QUERRI_PROJECT_ID	Use this project instead of the selected one.
--chat	QUERRI_CHAT_ID	Use this chat instead of the selected one.
--json		JSON output.
--quiet, -q		IDs only.
--no-interactive		Never prompt. --interactive forces prompts.
--verbose, -v		Prints details when your stored credentials can’t be read. It doesn’t log requests.
--version		Prints the version.

Command reference

Every command documents itself. Run querri --help, or querri <command> --help for any command.

Sign-in and profiles

querri auth login [--host URL] [--organization ORG_ID]
querri auth status
querri auth token                    # print the current access token
querri auth switch <profile>         # change the active stored profile
querri auth switch-org [org_id]      # change organization (interactive picker if omitted)
querri auth logout
querri whoami

Projects

querri project new "Name"                  # create and select
querri project list
querri project select <name|id>
querri project get [id]
querri project show [id]                   # the analysis steps as a diagram
querri project update [id]
querri project add-source <file_id>        # add an uploaded file to the project
querri project run [id] --wait             # run the project and wait for it
querri project run-status [id]
querri project run-cancel [id]
querri project delete <id>

Project chat

querri project chat -m "Question"          # ask in the selected project
querri project chat -m "..." --new         # start a new chat
querri project chat -m "..." --reasoning   # include reasoning
querri project chat show                   # conversation so far
querri project chat cancel

To work with chats directly:

querri chat list [project_id]
querri chat get [project_id] [chat_id]
querri chat new [project_id]
querri chat stream [project_id] [chat_id] -m "Question" --user-id <user_id>
querri chat cancel [project_id] [chat_id]
querri chat delete [project_id] [chat_id]

chat stream sends a message as a specific user. Set QUERRI_USER_ID instead of passing --user-id each time.

Steps

querri step list [project_id]
querri step data <project_id> <step_id> --page 1 --page-size 100

Files

querri file upload data.csv                # one file
querri file upload "data/*.csv"            # every file matching the glob
querri file list
querri file get <file_id>
querri file delete <file_id>

Sources

A source is a table of data, from an uploaded file, a connector, or rows you sent through the API.

querri source list
querri source get <source_id>
querri source describe <source_id>                      # columns and row count
querri source data <source_id> --page 1 --page-size 100
querri source query --source-id <source_id> --sql "SELECT * FROM data LIMIT 10"
querri source ask <source_id> "How many rows do we have?"
querri source new --name "Leads" --file rows.json      # or pipe a JSON array on stdin
querri source update <source_id>
querri source delete <source_id>
querri source connectors                                # connectors in your organization

In source query, the source is always a view named data. Write FROM data, never the source’s display name.

querri source sync calls an endpoint that isn’t implemented yet and returns an error.

Views

A view is a saved SQL query over your sources. You can write the SQL yourself, or describe what you want and let the AI write it.

querri view new --prompt "monthly revenue by product line"      # AI writes the SQL
querri view new --name "Orders" --sql "SELECT * FROM orders"    # your SQL
querri view chat <uuid> -m "filter to active customers only"    # refine it in chat
querri view list
querri view get <uuid>
querri view preview <uuid>
querri view run                                                  # materialize every view and wait
querri view run --view-ids <uuid1>,<uuid2> --no-wait             # start a run and return its run_id
querri view run-status <run_id>
querri view update <uuid>
querri view delete <uuid>

Dashboards

querri dashboard list
querri dashboard get <dashboard_id>
querri dashboard update <dashboard_id>
querri dashboard refresh <dashboard_id>
querri dashboard refresh-status <dashboard_id>

querri dashboard new and querri dashboard delete call endpoints that aren’t implemented yet and return an error.

Users

querri user list
querri user get <user_id>
querri user new --email user@example.com --first-name Alice --last-name Smith --role member
querri user update <user_id> --role admin
querri user delete <user_id>

--role is member or admin. On the People page in Querri, member shows as Creator.

Access policies

querri policy list
querri policy get <policy_id>
querri policy new --name "APAC Only" --source-ids <source_id> --row-filters '[{"column":"region","values":["APAC"]}]'
querri policy update <policy_id>
querri policy assign <policy_id> --user-ids <user_id>
querri policy remove <policy_id> <user_id>
querri policy resolve --user-id <user_id> --source-id <source_id>
querri policy columns --source-id <source_id>
querri policy delete <policy_id>

API keys

querri key list
querri key get <key_id>
querri key new --name "CI" --scopes "admin:projects:read,admin:projects:write" --expires-in-days 90
querri key delete <key_id>

key new also takes --bound-user-id, --rate-limit and --ip-allowlist. The secret is printed once, so save it straight away. See Authentication for what each option does.

Sharing

querri share project add <project_id> --user-id <user_id> --permission view
querri share project list <project_id>
querri share project remove <project_id> <user_id>

querri share dashboard add <dashboard_id> --user-id <user_id> --permission edit
querri share source add <source_id> --user-id <user_id>
querri share source org <source_id>                  # share a source with the whole organization
querri share source org <source_id> --disable

--permission is view or edit.

Embed sessions

For embedding Querri in your own app:

querri session new --user-id <user_id> --origin https://app.example.com --ttl 3600
querri session get --user <external_id> --access '{"sources":["<source_id>"],"filters":{"region":"APAC"}}'
querri session refresh --token <session_token>
querri session list
querri session revoke --token <session_token>
querri session ui-config --org <org_id>

--ttl is in seconds, from 900 to 86400. If your organization has a list of allowed embed domains, --origin is required and must be on the list.

Usage and audit

querri usage org --period current_month        # or last_month, last_30_days
querri usage user <user_id>
querri audit list --action api_key.create --all

Environment variables

Variable	Purpose
QUERRI_API_KEY	API key for scripts
QUERRI_ACCESS_TOKEN	An access token, used instead of an API key
QUERRI_ORG_ID	Organization ID
QUERRI_HOST	Server host (default https://app.querri.com; for local development, http://localhost)
QUERRI_PROJECT_ID	Project override, same as --project
QUERRI_CHAT_ID	Chat override, same as --chat
QUERRI_USER_ID	User for chat stream
QUERRI_TIMEOUT	Request timeout in seconds (default 30)
QUERRI_MAX_RETRIES	Retries for failed requests (default 3)

Tips

• Add --help to anything. querri project --help, querri view chat --help, and so on.
• Use --quiet inside scripts when you want a single ID back.
• Keep keys out of the command line. --api-key can land in your shell history, so set QUERRI_API_KEY instead.

Using Querri from an AI assistant

To ask Querri questions from inside an AI assistant instead of a script, use the MCP Server.