james.maesandClaude Fable 5.1 e65c8a4495 core+tui: the 13 priority todos: joins, quick filters, weekday, bulk paste, first N, scanner, counted views, variants on records
- 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>
2026-10-31 19:18:44 -05:00
2026-10-15 11:47:21 -05:00
2026-10-15 10:56:15 -05:00

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; --browser uses the authorization code with PKCE on a loopback redirect. Tokens are refreshed before they expire; qqq logout --provider-logout also 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_TOKEN overrides everything with a bearer token.
  • qqq doctor checks 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

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

S
Description
Reference CLI for the QQQ UI API (/qqq/v1), with the generated TypeScript client, a mock server and a conformance suite for client authors.
Readme Apache-2.0
8.4 MiB
0 Stars 2 Watchers 0 Forks
Languages
TypeScript 93.3%
Shell 2.5%
JavaScript 2.1%
Python 2%
PowerShell 0.1%