lql-cli 0.5.0

lql — CLI for the Liquid DataViewer platform

lql — Liquid Query Language CLI

Scriptable CLI for the Liquid DataViewer platform. Designed for both humans and AI agents (Claude Code, Codex, etc.) to automate datasets, eval analysis, spec docs, annotations, and more.

A Python package (Python ≥ 3.12), published on PyPI as lql-cli — the installed command is lql.

Quick start

uv tool install lql-cli               # install the CLI (or: pipx install lql-cli); the command is `lql`
lql login                             # authenticate (opens a browser)
lql skills install                    # teach Claude Code + Codex how to use lql

Install

lql is a Python package (requires Python ≥ 3.12), distributed on PyPI as lql-cli (the command it installs is lql). Install it as a standalone CLI tool with uv:

uv tool install lql-cli

Or with pipx / pip:

pipx install lql-cli
# or
pip install lql-cli

Run it without installing:

uvx --from lql-cli lql instructions

Or build from source:

git clone https://github.com/Liquid4All/lql
cd lql
uv tool install .     # or: pip install -e .

Update to the latest version with lql update --run, which detects how lql was installed (uv tool / pipx / pip) and runs the matching upgrade. Run lql update (no flag) to just print the command without executing it.

Authentication

Interactive login (browser)

lql login

Opens a browser window. After authorizing, credentials are saved to ~/.lql/config.json.

Non-interactive (API key)

export LQL_API_KEY=ak_live_...
lql login         # stores key in config
# or skip config entirely — just set the env var

Logout

lql logout

Environment variables

Variable	Description
LQL_API_KEY	API token (bypasses config file)
LQL_API_URL	Override API base URL
LQL_HF_TOKEN	HuggingFace token (required for datasets upload)
LQL_EVAL_WORKSPACE	Default workspace for eval list
LQL_ALLOW_INSECURE_API_URL	Set to 1 to allow a plaintext http:// API URL to a non-loopback host (off by default — the token is only sent over HTTPS or to localhost)

Command reference

Running a group with no subcommand (e.g. lql datasets) lists its subcommands. For faster typing, aliases and unique prefixes resolve everywhere: group aliases (ds, ws, ev, ann, hl, rep, bkt, iss), verb aliases (ls=list, rm/del=delete, new/mk=create, info=show), and prefixes (lql datasets l → list). So lql ds ls --workspace <id> ≡ lql datasets list --workspace <id>. The canonical names below always work (use those in scripts).

Auth

lql login                        Authenticate (browser or LQL_API_KEY)
lql logout                       Revoke key and clear profile
lql whoami                       Show current user

Workspaces

lql workspaces list [--search <text>]            List workspaces (--search filters by name/slug)
lql workspaces create <name>                     Create a workspace
lql workspaces show <id>                         Show workspace details
lql workspaces update <id> --name <n>            Rename a workspace
lql workspaces delete <id>                       Delete a workspace
lql workspaces members list <id>                 List members
lql workspaces members add <id> <email>          Add member by email
lql workspaces members remove <id> <uid>         Remove member by user ID

Datasets

lql datasets list [--workspace <id>] [--search <text>]   List datasets (--search filters by name/HF repo)
lql datasets show <id>                           Show dataset details
lql datasets create --workspace <id> --hf-repo <repo> [--name <n>] [--split <s>]
lql datasets create --workspace <id> --hf-bucket <org/bucket> --key <path-or-glob> [--name <n>]
                                                 From an HF storage bucket (e.g. --key 'data/*.parquet')
lql datasets sync <id>                           Trigger sync (HF repo, S3, or HF bucket)
lql datasets schema <id>                         Show column schema
lql datasets rows <id> [--limit N] [--offset N]  Fetch rows
lql datasets delete <id>                         Delete dataset
lql datasets push <id>                           Push to HuggingFace
lql datasets push-status <id> [--job <id>]       Check push job status
lql datasets upload <file> --workspace <id> --name <repo-name> [--split <s>]
                                                 Upload local file → HF → dataset

datasets upload requires LQL_HF_TOKEN.

Preview

View dataset samples in the terminal — a Textual TUI with a chat-style layout (user turns on the right, system/assistant/tool on the left). It renders the same formats as the DataViewer web UI: OpenAI {role, content}, structured/ multimodal content (text/image/audio), ShareGPT {from, value}, native OpenAI tool_calls, plus <think> reasoning blocks, <|tool_call_start|>…<|tool_call_end|> / Python / XML / JSON tool calls, tool results, tool-definition tables, and code.

Works on a local .jsonl/.json file, a platform dataset ID, or — with --hf — a HuggingFace repo. No browser, and nothing to forward over SSH — it's just the terminal.

lql preview <file.jsonl|file.json>     Local file: each line/object is a row
lql preview <dataset-id>               Platform dataset (fetched & paged lazily)
lql preview <org/name> --hf            HuggingFace repo: sync to DataViewer, then view
lql preview <src> -c <field>           Force field(s) as conversations (repeatable)
lql preview <src> -n <N>               Page size when paging a platform dataset
lql preview <src> --offset N           Start at row index N
lql preview <src> --title "<title>"    Title shown in the viewer header

HuggingFace datasets (--hf). lql preview org/name --hf syncs the repo into a DataViewer workspace, then opens it. You pick the target workspace from an interactive list (or pass --workspace <id>; --split defaults to train). Already-synced repos are reused — no duplicate, instant re-open.

lql preview tatsu-lab/alpaca --hf
lql preview org/name --hf --split validation --workspace <id>

Media. Images render inline in terminals that support an image protocol (Kitty/Ghostty, iTerm2, Sixel; falls back to a compact 🖼 … placeholder elsewhere) — both multimodal image_url/data-URI segments and image-mode columns. Audio can't play inline in a terminal, so each clip shows a ♪ line and p plays the current sample's audio via the system player (afplay/ open). Images render inline in pager mode (one sample at a time); scroll mode shows placeholders to avoid decoding the whole buffer.

Navigation — two modes, toggle with m / Tab:

• pager (default): one sample at a time · ←/→ or n/b switch samples · ↑/↓/j/k/PgUp-Dn scroll
• scroll: all samples in one buffer · n/b jump between samples · arrows scroll
• p play audio · q quits

lql preview examples/agent-traces.jsonl     # 20-sample file of agent-trace/tool-use formats
lql preview <dataset-id>                     # browse a platform dataset, paged on demand

Evals (dataset analysis)

Eval datasets are evaluation-run output — each row a sample with a model response and a correct verdict. They're detected automatically. These commands are the data primitives for error analysis: they slice and summarize the dataset, and you do the reasoning over what they return.

lql eval list [--workspace <id>]                 List eval datasets only
                                                 Defaults to LQL_EVAL_WORKSPACE; without a
                                                 workspace, lists only evals you own.
lql eval correctness <id>                        Fast accuracy + correct/incorrect/missing counts
lql eval stats <id>                              Accuracy + error-type distribution + token stats
lql eval samples <id> [--filter correct|incorrect|missing|all]
                       [--search <text>] [--error-type <value>]
                       [--columns a,b] [--limit N] [--offset N]
                                                 Slice the dataset for error analysis. Filters
                                                 AND together; prints an `index` column per row.
lql eval sample <id> --row <index>               Read one full sample (the conversation) by the
                                                 `index` returned from `eval samples`

Notes:

• --search matches a substring on the prompt or response column (either hit counts). Override the searched columns with --search-columns a,b.
• --error-type values come from the error_field / error_distribution reported by eval stats.
• Use the index from eval samples directly as eval sample --row <index>.

Typical analysis loop:

lql eval list --workspace <id>                   # find the eval dataset
lql eval stats <id>                              # accuracy + where the errors cluster
lql eval samples <id> --filter incorrect --limit 20   # pull the misses
lql eval sample <id> --row 42                    # read one failure in full

Edits

lql edits list <dataset_id> [--limit N]          List edits
lql edits count <dataset_id>                     Count edits
lql edits add <dataset_id> --row <ext_id> --column <col> --value <json>
lql edits delete <dataset_id> <edit_id>          Delete an edit

Spec docs

lql spec show --workspace <id>                   Show current spec doc
lql spec pull --workspace <id> [-o <file>] [--stdout]
                                                 Pull markdown (writes SPEC.md by default)
lql spec push --workspace <id> [--file <f>] --message <m> [--base-version-id <id>]
                                                 Defaults --file to SPEC.md; --message required
lql spec history --workspace <id>                Version history
lql spec diff --workspace <id> --version-id <id> [--compare-to <id>]
lql spec generate --workspace <id>               AI-generate a spec from the workspace's datasets

push auto-detects create-vs-update: with no existing doc it creates v1, otherwise it commits on top of the current HEAD (auto-resolved unless --base-version-id is given). On conflict (409), spec push exits with code 4 — pull again, re-apply, and push.

Review (annotations, highlights, issues, reports)

These act directly on a dataset — the CLI resolves the dataset's review session for you, so you never manage sessions by hand. Advanced: pass --session <id> to target a specific session for multi-pass review (a session id is returned in the JSON of any annotation/highlight/report).

Annotations

lql annotations list <dataset_id> [--session <id>]
lql annotations add <dataset_id> --row <ext_id> [--rating <n>] [--note <str>] [--session <id>]

Highlights

Highlights mark a text span (--start/--end are character offsets into the row's --column value).

lql highlights list <dataset_id> [--session <id>]
lql highlights add <dataset_id> --row <ext_id> --column <col> --start <n> --end <n> --text <str>
                  [--issue <id>] [--color <hex>] [--note <text>] [--session <id>]

Issues

A per-dataset taxonomy (name/color) used to tag highlights via highlights add --issue <id>.

lql issues list <dataset_id>
lql issues create <dataset_id> --name <str> [--description <str>] [--color <hex>]

Reports

lql reports list <dataset_id> [--session <id>]
lql reports show <report_id>                     Show a report
lql reports create <dataset_id> --title <title> [--summary <text>] [--session <id>]
                                                 Publish a report (bundles annotations + LLM analysis)

Buckets

S3-compatible:

lql buckets list                                 List S3 buckets
lql buckets show <id>                            Show bucket details
lql buckets probe <id>                           Test bucket connectivity + credentials
lql buckets objects <id> [--prefix <str>]        List objects
lql buckets attach <bucket_id> --workspace <id>  Attach bucket to workspace
lql buckets detach <bucket_id> --workspace <id>  Detach bucket from workspace

Hugging Face buckets (connect → add datasets; auth is your HF token):

lql buckets list-hf                              List HF bucket connections
lql buckets connect-hf <owner/bucket> --workspace <id> [--label <l>] [--hf-key <id>]
                                                 Connect an HF bucket and attach it to a workspace
lql buckets create-dataset <bucket_id> --workspace <id> --key <path-or-glob> [--name <display>]
                                                 Create a dataset from a connected HF bucket

Skills (agent setup)

Install the lql agent skill so coding agents (Claude Code, Codex) know how to use lql. The skill is a thin pointer that tells the agent to run lql instructions, so it never goes stale.

lql skills install [--tool claude|codex|both] [--project] [--force]
                                                 Install to ~/.claude and ~/.codex (both, by default)
lql skills uninstall [--tool claude|codex|both] [--project]

--project installs into ./.claude and ./.codex in the current directory instead of the home dir.

Instructions

lql instructions                                 Print the full agent reference (all commands,
                                                 flags, examples, and workflows) in one read

Update

lql update                                       Detect install method (uv/pipx/pip), print upgrade cmd
lql update --run                                 Detect and run the upgrade in place

Global flags

All commands accept:

Flag	Description
--json	Output raw JSON to stdout
--profile <name>	Use a named config profile
--api-url <url>	Override the API base URL

Exit codes

Code	Meaning
0	Success
1	General error
2	Unauthenticated / forbidden
3	Not found
4	Conflict (e.g. spec push version conflict)
5	Server error

Config file

~/.lql/config.json (mode 0600):

{
  "current_profile": "default",
  "profiles": {
    "default": {
      "token": "ak_live_...",
      "key_id": "uuid",
      "api_url": "https://liquid-anchor-api.fly.dev"
    }
  }
}