CLI

For a first notebook, follow Get started with CLI.

For installation and downloads, see the Querio CLI repository.

Update the CLI

Run querio update --check to check for a newer release, then querio update to install it. Both support --json. The updater verifies the download's SHA256 and version before replacing the executable; your credentials and workspace selection stay in place. The executable's directory must be writable.

Self-update supports release binaries on macOS and Linux, for AMD64 and ARM64. Use your package manager for package-managed installations. Development builds cannot self-update. If your binary has no update command, install a current release from the CLI repository.

Syntax and output

Prefix each listed command with querio. Replace uppercase names with your values; brackets mark optional arguments.

querio --help
querio notebook-session create --help
querio version --json

• --help or -h shows command-specific help. querio help COMMAND also works. --version or -v prints the CLI version.
• Add --json to commands that support it for structured output. It is a command flag, not a global flag. Rows marked JSON already return JSON without it.
• Progress, login/setup URLs, and recovery instructions go to stderr. Keep stderr separate when parsing stdout.
• Exit status 0 means the command succeeded. A submitted run, ready session, or accepted cancellation is not necessarily a completed run.
• Errors exit nonzero. Failed or cancelled run and job reads, and failed code exec, can still return JSON on stdout. Check the exit status and the result.

files get writes file bytes, notebook-session events streams server-sent events, git patch writes patch bytes unless given --json, and completion writes a shell script. These outputs are not JSON envelopes.

Login and workspace selection

Login uses a loopback browser callback and waits up to five minutes. With --no-browser, keep the command running and open its URL in a browser that can reach the terminal's machine. This is not a remote device-code flow. Successful login clears the previous saved workspace selection; reconnect to your workspace with workspace use WORKSPACE_ID.

Login service URLs require HTTPS, except HTTP on localhost or 127.0.0.1. Query strings, fragments, and embedded credentials are rejected.

Workspace and session IDs select where a command runs; they grant no access. Commands use the authenticated identity's permissions. See Users, roles and groups.

Workspace setup and files

Initialize a workspace or context repository

init [NAME] accepts the name argument or --name NAME, but not both. Names must contain 1-120 characters after trimming. Hosted setup creates and selects a workspace; it does not add access to an existing one.

An interactive terminal can prompt for Git and context selection; set the flags explicitly in scripts. Git setup preserves existing starter files and unrelated TOML values, but rewrites TOML formatting and comments. It does not stage, commit, upload, or publish files. A hosted Git workspace starts without hosted context seeds.

On provisioning failure, retry with the same name and printed request ID. If creation succeeded but selection failed, keep the returned workspace ID and use workspace use after resolving the error. Do not create another workspace. CLI-created workspaces start with Startup entitlements, without a Stripe subscription or trial. Metered allowances do not reset until a subscription supplies a billing period. Existing access and provisioning limits still apply.

For the repository and publishing procedure, see Sync context with Git.

Workspace files

See Files and versions for canonical files, working copies, and path rules.

For recursive uploads, globs are relative to the source directory. * matches within one path component; ** spans zero or more directories. Exclusions win. .gitignore is not interpreted. The CLI skips symlinks, special files, .env/.env.*, .pem/.key, and directories .git, .querio, .hg, .svn, node_modules, .venv, __pycache__, and .ssh. These filters are not secret detection.

querio files upload ./docs memory/repo --include '**/*.md' --exclude 'drafts/**' --dry-run --json

--dry-run shows an offline plan; it cannot check remote permissions or conflicts. Actual uploads require file read/write access, create missing parent directories, and stop at the first failure. Keep source files unchanged during transfer. An empty dry-run selection is valid; an actual upload with no matches fails.

Uploads are sequential and have no rollback, deletion, or automatic retry. JSON reports planned during dry-run, then uploaded, failed, or not_attempted during transfer. Earlier writes remain after failure. A connection failure can follow a completed write: inspect the remote file before retrying.

Notebooks and execution

Saved notebooks

--code imports one Python file as a single cell. --file accepts a notebook serialization JSON object, rather than the full notebook get response. Choose only one input flag; either accepts - for stdin. A supplied title must not be blank. These import flags do not define a notebook filesystem layout.

Title-only updates can run while a session is open. Replacing saved cells requires the session to be closed; use Code Mode for live edits. If --expected-updated-at is omitted, the CLI fetches the timestamp immediately before updating. A conflict fails without an automatic overwrite retry.

Environments and notebook sessions

Use Execution reference for the full state and lifecycle model. An environment supplies compute; a session opens a saved notebook in it. For explicit CLI/API opens, each notebook and environment supports one active notebook session. Use separate environments for concurrent notebooks, and close only sessions you own.

environment is an alias for execution-environment.

Session creation does not execute cells. --wait on creation waits only for readiness and leaves resources open. A failed or timed-out wait also leaves cleanup to you; use the printed session ID to inspect it.

Datasources and query variables belong to session configuration. Repeat --datasource, or supply comma-separated slugs. Use --variable region=GB for query variables; these do not become Python globals. Deliberately close and reopen a session to change configuration.

Interactive execution and offline skills

Use code exec and Code Mode to author, inspect, edit, and run cells in a live session. Read the bundled authoring reference with querio code skill --reference notebook-authoring. Cell mutations use top-level async with code_mode.get_context(). Scratchpad assignments are transient; create cells for saved code. Keep the command attached while it runs; interruption does not roll back completed effects.

In an editable session, code exec waits for the notebook to save before reporting success. A save failure does not undo execution. Keep the session open, inspect its cells, and resolve the save error before closing. Do not replay authoring code or submit a durable run as a save step. Runtime values are separate from saved code; reopening can require re-execution.

The bundled workflow and reference need neither login nor network access. Skill extraction refuses existing destinations; --output-dir cannot be combined with --reference. If extraction is incomplete, inspect the destination before retrying.

Durable runs, waits, and cleanup

Use notebook run for a separate one-shot run, and notebook-session execute for whole-notebook durable execution in an existing session. Neither is a required step after interactive Code Mode edits.

Wait timeouts do not cancel durable runs. For notebook run --wait, a wait timeout also leaves the runtime open. Keep the returned or printed IDs, inspect with runs get/runs wait, and close the session before its environment. If cancellation is needed, request it explicitly and wait for a terminal status. Saved notebooks remain after runtime closure. Resolve failed close operations before closing the environment.

Runs and preview jobs

The jobs group targets a preview API and is not an available background-introspection workflow. Datasource introspection is synchronous and returns its result directly. Do not use a catalog result as a job ID.

Datasource setup

Slugs contain 1-120 letters, digits, dots, underscores, or hyphens, starting with a letter or digit. The two creation modes have different rules:

• Manual: --connection-file FILE reads one connection JSON object, with a 1 MiB maximum. Use an owner-only file (chmod 600 on Unix-like systems) or --connection-file - for stdin. Optional --name NAME; testing is opt-in with --test-connection. Obtain the current schema with datasource schema.
• Browser: --browser opens the connection form and polls for configured metadata at the selected slug. Optional --no-browser prints the setup URL. This URL can be used across machines because setup uses polling, unlike login's local callback. Browser setup takes the name in the form and tests before saving; do not combine it with manual --name or --test-connection flags.

The browser and CLI each need workspace access. The setup link grants none and contains no credentials. Polling completes when configured metadata appears at the slug; it does not reserve the slug or prove which browser created it. A timeout or cancellation stops waiting, but a save may still finish. Inspect datasource get SLUG before retrying. configured: true alone does not prove query permission; see Users, roles and groups.

Without targets, introspection pulls all schemas. --refresh updates already-catalogued tables rather than discovering new ones. --all cannot be combined with --target or --refresh. The result includes the catalog path and counts, not a background job. Cancellation does not roll back catalog writes; inspect the result before retrying.

Git

These commands require the workspace file mode that keeps edits in separate working copies. CHANGESET_ID identifies a Querio working copy, not a Git branch. See Files and versions for state definitions and Sync context with Git for the reviewed publishing workflow.

Upload reads the committed configuration and committed file bytes. Uncommitted changes are ignored. --config is repository-relative; the committed TOML must contain context includes and a stable repository identity, unless --repository supplies the identity. Exclusions win. context.root locates context; it does not restrict upload selection. Git upload excludes .querio paths; review the committed selection rather than assuming the recursive file-upload filters apply.

git upload --dry-run is offline. Actual upload creates an immutable source version and leaves canonical unchanged. Selected contents are limited to 48 MiB and the encoded upload to 64 MiB. Use execution-environment create --changeset CHANGESET_ID to open the checked-out working copy.

Pause writers before exporting a patch. Check the command's exit status before applying its output, then reconcile against the source commit locally. CLI Git commands do not push to a forge, create or merge a PR, or verify approval.

Promotion replaces previously Git-managed files and removes managed files absent from the new selection, while preserving unrelated outputs. Existing working copies remain unchanged. Publication is not filesystem-atomic. A stale canonical version fails; inspect the changed state rather than blindly retrying.

Errors and environment variables

Errors and recovery

The CLI does not automatically retry mutations. Resolve permission, configuration, concurrency, or persistence errors before trying again.

Environment variables and precedence

Both token and API URL must be set to use environment credentials. Otherwise API commands use the stored login, refreshing it when needed. An API URL set alone does not retarget existing stored credentials. Explicit login URL flags override their environment defaults; later commands use the URLs saved by that login.

workspace use requires the stored login, even when environment credentials are present. Hosted init also needs that stored login to select the newly created workspace. Unset stale automation overrides before returning to interactive use. Keep tokens out of command arguments, notebooks, logs, and source control.

Version and shell completion

For a first notebook and its expected output, follow Get started with CLI.