Querio CLI preview

The CLI preview lets an external coding agent upload context, author notebooks, execute them, and inspect results without using Querio's agent API. The files and notebook commands require the v3 Files and notebook resource APIs on your deployment.

Sign in and select a workspace

querio login
querio init --name Acme --json

Login opens the existing Auth page in your browser. If you need an account, select Sign up, enter your email/password, accept the terms, and enter the emailed four-digit verification code. You do not need to enter your password a second time. After verification, the browser returns control to the waiting CLI without visiting app onboarding.

Existing users can sign in directly. Google and configured company SSO preserve the CLI return path and retain their existing account policies. New Google signup requires a Google Workspace account. Email/password accounts must verify their email before receiving CLI credentials.

Login does not create a workspace. init provisions a workspace owned by your user, with Classic entitlements and a remote filesystem. It does not create a Stripe subscription or a time-limited trial. Billing can be attached later. Existing account and domain limits still apply.

init selects the workspace it creates but does not create local project files. If selection fails after creation, use the returned id with querio workspace use <id> instead of creating another workspace. To use an existing workspace instead:

querio workspace list --json
querio workspace use <workspace-id>

login --no-browser prints the browser URL to stderr. The browser still needs to reach the CLI's local callback; this is not a remote device-code login.

CLI login requests only offline_access to obtain refresh tokens; it grants no API permissions. User login tokens use your current workspace permissions. Group-policy changes and membership removal apply without signing in again. Workload tokens use the service's current policy. Personal access tokens inherit their owner's current policy in the token's workspace and can receive service-specific grants; legacy scope fields do not limit permissions. Token exchange is not supported.

Connect a datasource

Use the browser form to keep database credentials out of your terminal and agent chat:

querio datasource add warehouse --browser --json

The CLI prints a link for the selected workspace and waits up to ten minutes. Sign in to the browser with access to that workspace, choose the database type, and enter its credentials. The form fixes the requested slug and tests the connection before saving. After Datasource ready, return to your terminal. The CLI prints metadata, never the connection credentials.

For a remote agent session, use --browser --no-browser and open the printed link on your own computer. Datasource setup does not require a localhost callback. The URL contains only the workspace and slug; it does not grant access. Browser and CLI authorization are checked independently.

The CLI rejects an existing slug before opening the form, then polls for that slug in the selected workspace. Another authorized member creating the same slug with credentials also completes the wait; this is not a separate approval or reservation system. Closing the browser, cancelling the form, Ctrl-C, or --timeout 2m does not undo a submitted save. Check querio datasource get warehouse before retrying after an interruption.

For manual setup, provide the canonical connection object from a protected JSON file or stdin:

querio datasource schema > connection-schema.json
chmod 600 connection.json
querio datasource add warehouse --connection-file connection.json --test-connection --json
querio datasource add other-warehouse --connection-file - --test-connection --json < connection.json
querio datasource get warehouse

connection.json contains the connection object, not the whole create-request envelope. See the datasource API for its shape. The CLI reads at most 1 MiB and requires owner-only file permissions on Unix. Keep credential files outside source control. Do not pass passwords or connection strings as command-line arguments.

datasource get can return configured: false when a datasource exists without credentials. That is valid metadata, not completed connection setup. configured: true does not prove that your account has permission to use the credential.

Manual mode accepts an optional --name. It tests before saving only when --test-connection is supplied; configured: true alone is not proof of connectivity. The schema comes from your server, not a separate CLI driver definition. Neither mode introspects tables automatically.

User login, PATs and workload OAuth tokens require the relevant current workspace and datasource permissions for their resolved user or service principal. Browser handoff does not bypass authorization. No credential readback or credential replacement command is provided.

Supply context and notebook code

Upload only the files you want Querio to have:

querio files put ./context.md memory/repo-context.md --json
querio files get memory/repo-context.md

Add --overwrite to replace an existing file. Use files mkdir <path> to create a directory and files list [path] --json to inspect it. Listing returns one page and an optional cursor for --cursor.

The external agent uses this context to author notebook code. Uploading a file does not automatically invoke a Querio agent or change a query. Files commands operate on canonical workspace context files, not the notebook editing API.

Open a notebook session

Create an empty saved notebook, then explicitly create its environment and session:

notebook_id=$(querio notebook create)
environment_id=$(querio execution-environment create)
export QUERIO_SESSION_ID=$(querio notebook-session create \
  --notebook "$notebook_id" --environment "$environment_id" --wait)
querio notebook-session get "$QUERIO_SESSION_ID"

Session creation is asynchronous. --wait waits for readiness without executing cells. Without it, use notebook-session wait <session-id>. The default mode is edit; --mode run opens a run-mode session.

Environments and sessions stay open until explicitly closed. A readiness timeout reports the session ID and does not silently delete it.

Supply --datasource warehouse and --variable region=GB on notebook-session create to configure that session. Variables are string values passed to the query gateway, not Python globals. Omitted configuration is empty, including when reopening a saved notebook. Session get exposes the active config.

Author and inspect through code mode

Keep an event stream open while working. This emits raw server-sent events, not a JSON document:

querio notebook-session events "$QUERIO_SESSION_ID" > notebook-events.sse &

Use the existing code exec command, with QUERIO_SESSION_ID set, to author cells without calling Querio's agent:

querio code exec --json <<'PY'
import json
from dataclasses import asdict
from code_execution_environment import code_mode

async with code_mode.get_context() as ctx:
    ctx.create_cell('price = 7\nquantity = 6', cell_id='inputs')
    ctx.create_cell('answer = price * quantity\nanswer', cell_id='answer')
    ctx.run_cell('answer')
print(json.dumps(asdict(ctx.result)))
PY

code exec uses the existing synchronous /api/cee/kernel/execute endpoint. Its JSON response contains success, output, stdout, stderr, and errors. It does not create a durable run record. A failed execution exits nonzero while still printing JSON.

Inspect current cells and runtime values, then revise cells in place:

querio code exec --json <<'PY'
from code_execution_environment import code_mode
ctx = code_mode.get_context()
print([(cell.id, cell.code) for cell in ctx.cells])
print(ctx.globals['answer'])
PY

querio code exec --json <<'PY'
from code_execution_environment import code_mode
async with code_mode.get_context() as ctx:
    previous = ctx.cells['inputs'].code
    ctx.edit_cell('inputs', 'price = 8\nquantity = 7')
    ctx.run_cell('answer')
print(ctx.globals['answer'])
PY

querio notebook get "$notebook_id"

Code mode also supports move_cell and delete_cell. Saved notebook reads expose persisted cells; ctx.globals exposes the current runtime's values. Reopening restores saved code, not computed globals, so execute cells again after reopening.

Interactive execution and automatic saving

Live interactive sessions use code mode, not notebook-session execute. Author, edit, run, and inspect cells through code mode using code exec. The notebook-session API supplies lifecycle and events, not interactive execution submission.

Leaving async with code_mode.get_context() applies the edits and requested executions. Cell-change and execution-completed events trigger automatic background saves. No separate execute, save, or close command is needed to save the notebook.

code exec waits for pending notebook saves. If saving fails, it reports the error and keeps the live session intact. Resolve the save failure without replaying the code. Do not submit a durable execution as a save or flush step. Durable-run workflows are separate from live interactive sessions.

Close, reopen, or update saved cells

querio notebook-session close "$QUERIO_SESSION_ID"
querio execution-environment close "$environment_id"

Close attached sessions before closing their environment. Closing a notebook session also closes its bound agents. Saved notebooks and run results remain readable. If recording closure fails after the runtime has closed, the error says so; retry the close operation after resolving the persistence failure, not the notebook execution. To reopen, create an environment and session again using the same notebook ID.

For closed notebooks, notebook update can replace serialization (--file) or import a single Python cell (--code). Creation accepts the same import flags; no import is required. Datasources and variables belong to session creation, not saved notebook creation/update. Close and reopen the session with the desired configuration to change them; omit the flags for empty configuration.

Supply --expected-updated-at from your last notebook get to reject stale updates. If omitted, the CLI fetches the current timestamp immediately before updating. Conflicts are reported, not retried. Use code mode, not saved-document replacement, for active notebook editing.

For separate, non-interactive one-shot runs, the convenience notebook run <id> command creates its own environment/session and accepts the same --datasource and --variable configuration flags. With --wait, it closes those resources on terminal completion. Without --wait, it returns their IDs; close them with notebook close <session-id> --environment <environment-id>. These cleanup semantics differ from the explicit notebook-session execute command.

notebook-session execute <id> runs the whole notebook through the run-all session event and leaves its resources open. Without --wait, JSON output contains success, runId, and conversationId. With --wait, it returns the terminal run. The command no longer accepts --cell or --request; use code exec for cell-level work.

Discover and introspect a datasource

querio datasource schemas warehouse --json
querio datasource tables warehouse --schema public --json
querio datasource introspect warehouse --all --json
querio datasource introspect warehouse --target public.orders --target public.customers --json
querio datasource introspect warehouse --target public --refresh --json

Introspection waits for the existing synchronous catalog endpoint and saves the catalog to workspace files. It returns the catalog path, counts, and per-schema results, not a job ID. Without targets, it pulls all schemas. Repeat --target to select schemas or tables. --refresh updates already-catalogued tables, optionally scoped to the supplied targets; it does not discover new tables in a selected schema. --all cannot be combined with targets or refresh. The default timeout is five minutes; use --timeout 10m to change it.

Cancellation and timeouts do not roll back catalog writes. Requests are not automatically retried. Read the catalog file before retrying if completion is uncertain.

Preview boundaries

Only the jobs commands still target a proposed background-job API without a server implementation. Datasource introspection does not use jobs.

Workspace creation is not automatically retried. init prints its request ID to stderr before sending the request and includes it in successful JSON output. After a timeout or provisioning failure, repeat the same name with --request-id <original-id>. This resumes or returns the same workspace rather than allocating another one. You can also supply a request ID on the first invocation for scripted retries. Retries require the original user's current workspaceOnboarding:manage permission. New workspaces receive default authorization groups, with the creator assigned to Owner.

init saves the created workspace as the current selection. QUERIO_WORKSPACE_ID still overrides that saved selection for workspace operations; unset it to use the selection saved by init.