qqq-cli/docs/release-notes/1.0.0.md

qqq 1.0.0

qqq is the command-line client and the full-screen terminal UI for QQQ applications, in one binary per platform. Everything it shows comes from the server's metadata through the QQQ UI API, so the same binary works with any QQQ application: tables, processes, reports, dashboards, records and the extensions (QBits) the server installs. Sign in once; the CLI (qqq <noun> <verb>) and the terminal UI (qqq ui) share the profiles and sign-ins.

Compatibility: servers on UI API 1.6.0 up to (not including) 2.0.0, that is QQQ 4.1.0-RC.15 or later. qqq --version shows the range; qqq doctor checks a server against it.

Install

curl -fsSL https://raw.githubusercontent.com/QRun-IO/qqq-cli/main/scripts/install.sh | sh -s -- --version 1.0.0

brew install qrun-io/tap/qqq                                             # macOS, Linux
scoop bucket add qrun https://github.com/QRun-IO/scoop-bucket; scoop install qqq    # Windows
npm install -g @qrun-io/qqq-cli                                          # GitHub Packages, Node 20+, CLI only

Or download the binary for your platform below and check it against SHA256SUMS:

Platform	File
macOS, Apple silicon	qqq-darwin-arm64
macOS, Intel	qqq-darwin-x64
Linux x64 / arm64 (glibc)	qqq-linux-x64, qqq-linux-arm64
Linux x64 / arm64 (musl, Alpine: apk add libstdc++ libgcc)	qqq-linux-x64-musl, qqq-linux-arm64-musl
Windows x64	qqq-windows-x64.exe

The npm package has the CLI without the terminal UI; the binaries have both.

macOS: these binaries are not notarized yet. A binary downloaded with a browser is stopped by Gatekeeper; clear the flag once with xattr -d com.apple.quarantine ./qqq-darwin-arm64. The installer and Homebrew do not set it. Windows: the .exe is not signed yet, so SmartScreen may warn on first run.

Get started

qqq login --server https://your-qqq-server       # device flow, browser (PKCE), Auth0, TABLE_BASED or a session
qqq home                                         # what you can open and do
qqq table query person -w "lastName STARTS_WITH S" --order -id -l 5
qqq process run greetInteractive -r 1,2 -v greetingPrefix=Hi
qqq ui                                           # the terminal UI on the same profile
qqq doctor                                       # connection, sign-in, terminal, and the build for support

Highlights of the terminal UI

qqq ui is a classic full-screen UI: a function-key bar at the bottom (F1 Help, F2 Search, F3 View, F4 Edit, F5 Refresh, F6 Filter, F7 New, F8 Delete, F9 Menu, F10 Quit; Esc then a digit when your terminal keeps the F-keys), Esc to go back, and a : command line that speaks the CLI grammar.

Key	What it does
F2	Search: records across tables as you type (quick search), with the matched field, Enter to open, o for the filtered grid, Space to mark hits for actions
/ (also ., Ctrl+K)	find anything: apps, tables, processes, widgets, reports, records, commands, help
F9	the menu in two levels, areas then entries (Context, Go to, Work, Connection, Settings, Help)
Ctrl+O	Servers: every saved profile with its short name, description and status; Enter switches
F6	the filter dialog: rows of field, operator and value, a live match count, an Advanced mode with a cheat sheet
Ctrl+P	print what you see: a record sheet, a whole table list, or any screen (printing extension)
? / F1	the keyboard reference of the screen
D	developer view of a record or a grid: security, events, scripts, JSON, metadata, audits, APIs
C P K T W, a	record collaboration (collaboration extension): comments, attachments, tasks, timeline, follow, share preview, who is viewing; a strip at the bottom of the record view and, from 140 columns, a Collaboration panel
Ctrl+G, :ask	the Assistant panel: ask about your data in plain language, with the record or grid on screen as context (Ctrl+D drops it); answers stream with their numbers and links that open the record or grid
:history, Ctrl+R	everything you did in the CLI and the TUI, to do again or copy as a CLI command; Ctrl+R on the : line searches it like bash
:sql	SQL Runner: editor, completion popups, result grid, export, notebooks, history (sql-workbench extension)
F2 or Ctrl+Space in a date field	the calendar picker; dates can also be typed in your format
S, x, y	column statistics (computed from loaded rows when the server has none), export (file names carry the local date and time), copy
:lock, :saver	the screen saver: live tiles in one compact group, Query, the qrun.io mascot and your profile's name in block letters; everything moves and it dims, so an OLED or CRT does not burn in (:saver burnin, :saver dim)

The mouse works everywhere (click, double-click, right click for actions, wheel, drag column edges; F9 › Settings › Mouse or --no-mouse turns it off). The CLI equivalent of a grid or dialog can be copied to the clipboard. Completion popups and text or HTML widgets (headings, status badges, aligned lists) are laid out to be read. Grids, records with forms and contingent pickers, the process wizard, bulk load, reports and saved reports, dashboards and widgets that act, every sign-in type, themes, and a terminal check (qqq ui --check) round it out.

Highlights of the CLI

• Tables: query, count, stats, get, create, copy, update, delete, export, children, downloads and uploads, variants, bulk insert, edit and delete from CSV or Excel.
• qqq assistant ask "<question>" streams the assistant's answer, then its numbers and the records and tables it refers to with the command that opens each (--table/--record for context, -c to continue, --json); qqq assistant config says whether it answers and with which model.
• qqq history: everything you did in the CLI and the TUI on the profile (--since, --grep, --kind, rerun <n>, clear); secrets are never written, QQQ_HISTORY=off turns it off.
• qqq table stats on a table without server column statistics computes them from the matching records (--local, --no-local, --max-records), and a closed pipe (| head -1) ends quietly.
• Default export names are <name>_<date>_<time>.<ext> in local time; a name you give with -o is used as given.
• Processes with every step screen, async jobs and cancel; reports and saved reports (pivots, schedules); saved views; sharing; audits; widgets and dashboards as text; home, find and search.
• -o/--out is always the output file and --order sorts (qqq table export person -o people.csv --order -id). Until 1.1, -o still sorts on the few commands that write no file, with a warning.
• Profiles: qqq profile list|add|edit|use|remove with a short name, a description and a sign-in mode.
• Printing: qqq print <table> <id...>, qqq print list <table>, qqq print text, qqq print job ... and qqq printer .... (qqq printing ... holds the 17 generated agent-side operations; table-list and text printing are the processes behind qqq print list and qqq print text.)
• Extension results print as key/value rows and sub-tables; qqq esb, qqq collab, qqq alerts, qqq health and one noun per extension; qqq api <operationId> calls any of the 219 UI API operations.
• JSON, table, text, CSV and YAML output with JMESPath --query; shell completion for bash, zsh, fish and PowerShell; sign-ins in the OS keyring.

Parity: every row of the web UI's acceptance matrix that applies to a terminal passes in both the CLI and the UI, or is blocked on a filed server issue (docs/parity/feature-matrix.md).

Assistant

Ctrl+G (or :ask) in the terminal UI and qqq assistant ask in the CLI talk to the server's in-app assistant: read-only, with your permissions. It needs the assistant extension (qbit-assistant) with a model provider configured on the server; the owner sets the provider and its key in the server's configuration (for the enterprise test server, ANTHROPIC_API_KEY in its private env file, else a local Ollama). Without the extension the entry is disabled and says what is missing; without a provider the panel and qqq assistant config show the server's reason (NOT_CONFIGURED) and what to configure.

Known limitations

• Text filters ask the server for case-insensitive matching, but servers do not read that option over the UI API yet (qqq#1358), so matching stays case-sensitive until they do.
• Jobs need a server with durable jobs. Auth0 sign-in is built but has not been tried against a real tenant (qqq-cli#10).
• Search needs the quick search extension and printing the printing extension (qbit-printing 2.x); without them the UI says so and offers no Print action.
• The binaries are not Developer ID signed or notarized, nor Authenticode signed. The Windows and Intel macOS binaries are cross-compiled and were not run before this release; the macOS and Windows CI lanes run the Node packages' build, tests and lint, not the binaries.

For developers: the enterprise test server

scripts/enterprise-server.sh starts a local "enterprise" QQQ server (qqq-all's enterprise profile: every locally runnable QBit plus the sample app) on port 8078 with mock authentication, backed by Redis, OpenSearch and a MinIO container for object storage. Its credentials and state live in a private directory under ~/.local/state/qqq-enterprise. --status, --stop and --log manage it, and scripts/enterprise-smoke.sh sweeps the CLI over every QBit surface. scripts/print-agent.sh runs a virtual print agent for the printing extension. The tmux smoke test for the UI takes --server URL and --profile NAME: packages/tui/scripts/smoke.sh.

Full list of changes: CHANGELOG.md.