- Exposed joins (QRY-020/021, REC-064): grid columns and filters take
joinTable.field (labels "Join: Field"); the kernel ResultCursor sends
the planned joins with query and count and reads the distinct count for
many-side joins ("3 rows (2 distinct)"); record sections show fields of
readable exposed joins through a joined query for the record.
- Quick filters (QRY-080/081): the filter dialog starts with the table's
quick filter fields (defaultQuickFilterFieldNames, else T1) and an add
row whose fields are remembered per table.
- Weekday criteria (QRY-085): the kernel grammar reads weekday(field) IN
1-7 or day names into a WeekdayOf fieldFunction (DATE_TIME fields get
WeekdayOfDateTime with the instance's arguments); the builder offers day
of the week is any of / none of. The sample rejects it: server finding 23.
- Bulk paste (QRY-088): list values accept pasted text split on commas,
tabs, semicolons and new lines, choice labels resolved to ids, with the
instance's bulkAddFilterValues help; bracketed paste reaches the focused
editor everywhere.
- First N (QRY-033): table processes run on the selection, the cursor
record, the whole result, or its first N records.
- Scanner screens (PRC-044): no heading or step list; Enter submits.
- Counted quick views (QRY-094): doCount views show their counts.
- Variant (REC-063): records and forms opened from a variant grid read
with tableVariant.
- The grid shows a failed query instead of keeping the previous rows.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
qqq-cli
qqq is the command-line client for QQQ applications. It talks to a
QQQ server only through the UI API (/qqq/v1), the API the web UI uses too. Nothing about an
application is built in: apps, tables, fields, processes, widgets and extensions all come from the
server's metadata, so the same binary works against any QQQ application.
This is 1.0.0-rc.1, the first release candidate. It works with servers that serve UI API 1.6.0 up to
2.0 (QQQ 4.1.0-RC.15 or later); qqq --version prints the range.
The repository also holds the libraries the CLI is built on, for anyone writing a CLI, TUI or native client:
| Package | Version | What it is |
|---|---|---|
@qrun-io/qqq-cli |
1.0.0-rc.1 | qqq, the CLI |
@qrun-io/qqq-core |
1.0.0-rc.1 | the client kernel: sessions and keyring, metadata cache, filter grammar, forms, processes, records, render model, output formats. No terminal code |
@qrun-io/qqq-ui-api-client |
1.8.0-rc.2 | a typed TypeScript client generated from the merged UI API document (core plus 13 extensions), with OAuth2 device-flow and PKCE sign-in, token refresh and the realtime (SSE) stream |
@qrun-io/qqq-ui-api-conformance |
1.6.0-rc.2 | a read-only conformance suite for any UI API server, and qqq-dev-idp, a local OIDC provider for testing native clients |
packages/tui |
not released | qqq ui, the full-screen terminal UI (OpenTUI on Bun), in development |
Install
A single-file binary (no Node needed) for macOS (arm64, x64), Linux (x64, arm64; glibc, and musl for Alpine) or Windows (x64), from the releases:
curl -fsSL https://raw.githubusercontent.com/QRun-IO/qqq-cli/main/scripts/install.sh | sh # to ~/.local/bin
The installer picks the right build and checks it against the release's SHA256SUMS
(--version 1.0.0-rc.1, --dir /usr/local/bin). Homebrew and Scoop packages are drafted in
docs/packaging and land with the release.
Or from npm (GitHub Packages), with Node.js 20 or later:
echo "@qrun-io:registry=https://npm.pkg.github.com" >> ~/.npmrc
npm install -g @qrun-io/qqq-cli@rc
First sign-in
$ qqq login --server https://admin.example.com --profile prod
To sign in to https://admin.example.com, open:
https://auth.example.com/device?code=ED84-CC03
and confirm the code ED84-CC03 (it expires in 10 minutes).
Signed in to https://admin.example.com as darin@example.com; sign-in kept in the macos-keychain.
$ qqq whoami
$ qqq table query person -w "lastName STARTS_WITH S" -o -id -l 5
- OAuth2 and Auth0 servers use the device flow;
--browseruses the authorization code with PKCE on a loopback redirect. Tokens are refreshed before they expire;qqq logout --provider-logoutalso revokes them at the provider. MOCK and fully anonymous servers get a server session. - Profiles name servers, as
aws --profile:qqq --profile prod …,QQQ_PROFILE,qqq config profile list|use|remove. The first sign-in becomes the default. - Sign-ins live in the OS keyring: macOS Keychain, Secret Service on Linux, DPAPI on Windows, or a
0600 file with
QQQ_KEYRING=file(headless hosts).QQQ_TOKENoverrides everything with a bearer token. qqq doctorchecks the connection, the sign-in and the terminal.
The grammar
qqq <noun> <verb> [arguments] [options], with global options anywhere.
| Noun | Verbs |
|---|---|
table |
list, describe, query, count, stats, get, create, copy, update, delete, export, children, download, variants |
process |
list, describe, run (every step screen, async jobs with progress, Ctrl-C cancels on the server) |
apps, search, tail, whoami |
app homes, global search, the live event stream |
saved-view, audit, report, widget, job, prefs, help-search |
saved views, audit history, reports, dashboard widgets as text, jobs, preferences, help |
api <operationId> |
any of the 202 UI API operations by id: the escape hatch |
extensions, and one noun per extension |
esb, collab, health, alerts, assistant, sql-workbench, … gated on what the server has installed |
login, logout, config, cache, completion, doctor |
sign-in, profiles and settings, the metadata cache, shell completion (bash, zsh, fish, PowerShell) |
qqq table query person -g "(firstName = Avery OR firstName = Blair) AND birthDate > now(-40y)"
qqq table create pet --set name=Pixel --set personId=2 --set speciesId=Dog
qqq table export person -w "id <= 5" --fields id,firstName,email --out people.xlsx
qqq process run greetInteractive -r 1,2,3 -v greetingPrefix=Hi
qqq api getTableMetaData --path tableName=person -Q 'fields.*.label'
eval "$(qqq completion zsh)"
Output is a table on a terminal and JSON in a pipe; -O json|table|text|csv|yaml (or QQQ_OUTPUT)
chooses, and -Q reshapes it with JMESPath. Values are labels and display values from the server;
DATE_TIME values are shown in your zone (--utc for raw). Exit codes: 0 ok, 1 error, 2 usage or bad
filter, 3 auth, 4 server unreachable or rate limited, 5 not found, 6 validation, 70 server error,
130 interrupted. Every request carries X-QQQ-Client: cli/qqq-cli <version> for the server's audits.
TRY-IT.md walks through every command against the QQQ sample server.
Documentation
- TRY-IT.md: the CLI (and the TUI as it is built) against the local sample server
docs/parity/feature-matrix.md: CLI status of every row of the web UI's acceptance matrixdocs/extensions.md: the extension documents merged into the clientdocs/server-findings.md: UI API issues found while building the clientsdocs/review-2026-10-31.md: the hardening review of the CLI and kerneldocs/packaginganddocs/ci-lanes.md: install paths, release and CIpackages/core/README.md: the kernel's modules- QQQ's
UI-API-CLIENTS.mdandUI-API-CHANGELOG.md: the API itself - CHANGELOG.md
Writing a client
import { createUiApiClient, unwrap, getNativeSignInConfig, deviceSignIn } from '@qrun-io/qqq-ui-api-client'
const config = await getNativeSignInConfig('https://admin.example.com')
const tokens = await deviceSignIn(config, (p) => console.log(`Open ${p.verificationUriComplete}`))
const api = createUiApiClient({ baseUrl: 'https://admin.example.com', token: () => tokens.accessToken, clientChannel: 'tui/my-tui 1.0' })
const page = await unwrap(api.POST('/qqq/v1/table/{tableName}/query', {
params: { path: { tableName: 'person' } },
body: { filter: { criteria: [{ fieldName: 'lastName', operator: 'STARTS_WITH', values: ['K'] }], limit: 20 } },
}))
Paths, parameters, bodies and responses are typed from the document. @qrun-io/qqq-core adds the
pieces every client needs above that (filter grammar, forms with contingent fields, the process runner,
record view, output formats); see its README.
npm run mock serves the merged document with Prism on
http://127.0.0.1:4010, to build against without a server. To check a server:
qqq-ui-api-conformance --server https://admin.example.com # public checks only
qqq-ui-api-conformance --server https://admin.example.com --token "$T" # all read-only checks
qqq-dev-idp is a local OIDC provider (device grant, PKCE, refresh, revocation, RS256 JWTs) for testing
OAuth2 sign-in against a local QQQ server; TRY-IT.md has the recipe.
Development
npm ci
npm run build && npm test && npm run lint
npm run test:tui # the TUI's tests (Bun 1.4+)
npm run generate # regenerate the client and the operations index from the document
npm run spec:merge-extensions # remerge the extension documents (sample server running)
npm run binaries # dist/qqq-<os>-<arch>[.exe] and SHA256SUMS (Bun 1.4+); --host, --musl
npm run release # every release check, then the tag and publish commands (prints only)
The CLI runs on Node 20 and later and uses no Bun-only API; Bun is needed only to build the binaries
and for the TUI. CI is the qqq-orb cli profile (.qqq-ci.yml); a tag v<client version> publishes the
packages to GitHub Packages (see docs/ci-lanes.md for what it does and does not cover).
License
Apache-2.0