qsys-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Owens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# qsys-cli
+
+Control a running Q-SYS Core from the shell, over QSC's QRC protocol —
+works against real Core hardware and against **Q-SYS Designer in Emulate
+mode** (validated on a live Designer emulation). The human/scriptable
+sibling of [`q-sys-mcp`](https://www.npmjs.com/package/q-sys-mcp), built on
+the same [`qsys-qrc`](https://www.npmjs.com/package/qsys-qrc) client
+(keepalive + transparent auto-reconnect included).
+
+## Install
+
+```sh
+npm install -g qsys-cli   # installs the `qsys` command
+npx qsys-cli status       # or one-shot, no install
+```
+
+(The npm package is `qsys-cli` — npm reserves the bare name `qsys` — but the
+installed command is plain `qsys`.)
+
+## Usage
+
+```sh
+export QSYS_HOST=192.168.1.10          # or pass --host on every call
+
+qsys status                            # engine/design status
+qsys ls --type gain                    # list components, filtered by type
+qsys get MainGain                      # read a named control
+qsys set MainGain -6 --ramp 2          # set it (negative values just work)
+qsys get-component Gain1               # all controls of a component
+qsys set-component Gain1 mute true
+qsys watch MainGain --interval 0.2     # stream changes until Ctrl-C
+qsys snapshot load Bank 1 --ramp 1
+```
+
+Every command takes `--json` for machine-readable output (`watch` emits JSON lines).
+Connection: `--host/--port/--user/--password` or `QSYS_HOST/QSYS_PORT/QSYS_USER/QSYS_PASSWORD`.
+
+Values coerce naturally: `true`/`false` → boolean, numeric → number, anything else → string.
+
+## Notes
+
+- QRC has no way to enumerate named controls or snapshot banks — you need to
+  know their names from the design (`ls` lists components that have script
+  access enabled).
+- `watch` uses QRC change groups; momentary trigger controls don't emit
+  change events (they never hold a value).
+
+## Disclaimer
+
+This is an independent open-source project, **not affiliated with, endorsed
+by, or supported by QSC, LLC**. "Q-SYS" is a trademark of QSC. The CLI
+speaks the publicly documented QRC protocol and contains no QSC code.
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * qsys — control a running Q-SYS Core (or qsys-emulator) over QRC from the
+ * shell. The human/scriptable sibling of qsys-mcp, over the same QrcClient.
+ *
+ *   qsys status --host 192.168.1.10
+ *   qsys set MainGain -6 --ramp 2
+ *   qsys watch MainGain --interval 0.2
+ *
+ * The published bin is the compiled dist/bin.js; in the workspace, run it
+ * via `npm -w qsys run qsys` (tsx) instead of executing this file directly.
+ */
+import { runCli } from './cli.js';
+const abort = new AbortController();
+process.on('SIGINT', () => abort.abort());
+process.on('SIGTERM', () => abort.abort());
+runCli(process.argv.slice(2), {
+    out: console.log,
+    err: console.error,
+    signal: abort.signal,
+}).then((code) => process.exit(code), (err) => {
+    console.error('qsys: fatal:', err);
+    process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,20 @@
+export declare class UsageError extends Error {
+}
+export interface CliIo {
+    out: (line: string) => void;
+    err: (line: string) => void;
+    /** Aborting stops a `watch` stream (bin wires SIGINT/SIGTERM here). */
+    signal?: AbortSignal;
+}
+export declare const USAGE = "usage: qsys <command> [args...] [flags]\n\ncommands:\n  status                                            engine/design status\n  ls [--type <substr>] [--filter <substr>]          list components\n  get <name...>                                     read named control(s)\n  set <name> <value> [--ramp <s>]                   set a named control\n  get-component <comp> [ctrl...]                    read component controls (all if none given)\n  set-component <comp> <ctrl> <value> [--ramp <s>]  set a component control\n  watch [--component <comp>] <ctrl...> [--interval <s>]   stream changes until Ctrl-C\n  snapshot load <bank> <slot> [--ramp <s>]          recall a snapshot\n  snapshot save <bank> <slot>                       save a snapshot\n\nconnection:\n  --host <ip>        Core/emulator address (or QSYS_HOST)\n  --port <n>         QRC port, default 1710 (or QSYS_PORT)\n  --user/--password  logon if the Core requires it (or QSYS_USER/QSYS_PASSWORD)\n  --timeout <s>      per-request timeout, default 10\n\noutput:\n  --json             machine-readable output (watch emits JSON lines)\n\nvalues: true/false \u2192 boolean, numeric \u2192 number, anything else \u2192 string.\nNegative values work as-is: qsys set MainGain -6";
+interface ParsedArgs {
+    flags: Record<string, string | boolean>;
+    positionals: string[];
+}
+/**
+ * Hand-rolled instead of node:util parseArgs so bare negative numbers stay
+ * positional — `qsys set MainGain -6` must not read `-6` as an option.
+ */
+export declare function parseCliArgs(argv: string[]): ParsedArgs;
+export declare function runCli(argv: string[], io?: CliIo): Promise<number>;
+export {};

package/dist/cli.js

@@ -0,0 +1,287 @@
+import { QrcClient } from 'qsys-qrc';
+import { CONTROL_HEADER, coerceValue, controlRow, renderKv, renderTable, } from './format.js';
+export class UsageError extends Error {
+}
+export const USAGE = `usage: qsys <command> [args...] [flags]
+
+commands:
+  status                                            engine/design status
+  ls [--type <substr>] [--filter <substr>]          list components
+  get <name...>                                     read named control(s)
+  set <name> <value> [--ramp <s>]                   set a named control
+  get-component <comp> [ctrl...]                    read component controls (all if none given)
+  set-component <comp> <ctrl> <value> [--ramp <s>]  set a component control
+  watch [--component <comp>] <ctrl...> [--interval <s>]   stream changes until Ctrl-C
+  snapshot load <bank> <slot> [--ramp <s>]          recall a snapshot
+  snapshot save <bank> <slot>                       save a snapshot
+
+connection:
+  --host <ip>        Core/emulator address (or QSYS_HOST)
+  --port <n>         QRC port, default 1710 (or QSYS_PORT)
+  --user/--password  logon if the Core requires it (or QSYS_USER/QSYS_PASSWORD)
+  --timeout <s>      per-request timeout, default 10
+
+output:
+  --json             machine-readable output (watch emits JSON lines)
+
+values: true/false → boolean, numeric → number, anything else → string.
+Negative values work as-is: qsys set MainGain -6`;
+/** Flags taking a value; everything else that starts with `--` must be boolean. */
+const STRING_FLAGS = new Set([
+    'host', 'port', 'user', 'password', 'timeout',
+    'type', 'filter', 'ramp', 'component', 'interval',
+]);
+const BOOL_FLAGS = new Set(['json', 'help']);
+/**
+ * Hand-rolled instead of node:util parseArgs so bare negative numbers stay
+ * positional — `qsys set MainGain -6` must not read `-6` as an option.
+ */
+export function parseCliArgs(argv) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--') {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            const name = eq === -1 ? a.slice(2) : a.slice(2, eq);
+            if (BOOL_FLAGS.has(name)) {
+                if (eq !== -1)
+                    throw new UsageError(`--${name} takes no value`);
+                flags[name] = true;
+            }
+            else if (STRING_FLAGS.has(name)) {
+                const value = eq === -1 ? argv[++i] : a.slice(eq + 1);
+                if (value === undefined)
+                    throw new UsageError(`--${name} requires a value`);
+                flags[name] = value;
+            }
+            else {
+                throw new UsageError(`unknown option --${name}`);
+            }
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    return { flags, positionals };
+}
+function numFlag(raw, name) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        throw new UsageError(`invalid --${name}: ${String(raw)}`);
+    return n;
+}
+function need(positionals, count, shape) {
+    if (positionals.length < count)
+        throw new UsageError(`expected: ${shape}`);
+}
+export async function runCli(argv, io = { out: console.log, err: console.error }) {
+    let flags;
+    let positionals;
+    try {
+        ({ flags, positionals } = parseCliArgs(argv));
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            io.err(`qsys: ${err.message}`);
+            io.err(USAGE);
+            return 2;
+        }
+        throw err;
+    }
+    if (flags.help) {
+        io.out(USAGE);
+        return 0;
+    }
+    const cmd = positionals[0];
+    const rest = positionals.slice(1);
+    if (!cmd) {
+        io.err(USAGE);
+        return 2;
+    }
+    const host = flags.host ?? process.env.QSYS_HOST;
+    if (!host) {
+        io.err('qsys: --host (or QSYS_HOST) is required');
+        return 2;
+    }
+    let client;
+    try {
+        const port = numFlag(flags.port ?? process.env.QSYS_PORT, 'port') ?? 1710;
+        const timeoutS = numFlag(flags.timeout, 'timeout') ?? 10;
+        client = new QrcClient({
+            host,
+            port,
+            requestTimeoutMs: timeoutS * 1000,
+            // One-shot commands should fail fast; only a watch stream rides out drops.
+            reconnect: cmd === 'watch',
+        });
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            io.err(`qsys: ${err.message}`);
+            return 2;
+        }
+        throw err;
+    }
+    const json = flags.json === true;
+    try {
+        await client.connect();
+        const user = flags.user ?? process.env.QSYS_USER;
+        const password = flags.password ?? process.env.QSYS_PASSWORD;
+        if (user !== undefined && password !== undefined)
+            await client.logon(user, password);
+        switch (cmd) {
+            case 'status': {
+                const s = await client.statusGet();
+                if (json) {
+                    io.out(JSON.stringify(s, null, 2));
+                }
+                else {
+                    io.out(renderKv([
+                        ['Design', `${s.DesignName} (code ${s.DesignCode})`],
+                        ['Platform', s.Platform + (s.IsEmulator ? ' (emulator)' : '')],
+                        ['State', s.State],
+                        ['Status', `${s.Status.Code} ${s.Status.String}`],
+                        ['Redundant', String(s.IsRedundant)],
+                    ]));
+                }
+                return 0;
+            }
+            case 'ls': {
+                let comps = await client.getComponents();
+                const type = flags.type?.toLowerCase();
+                const filter = flags.filter?.toLowerCase();
+                if (type)
+                    comps = comps.filter((c) => c.Type.toLowerCase().includes(type));
+                if (filter)
+                    comps = comps.filter((c) => c.Name.toLowerCase().includes(filter));
+                if (json)
+                    io.out(JSON.stringify(comps, null, 2));
+                else
+                    io.out(renderTable(['NAME', 'TYPE'], comps.map((c) => [c.Name, c.Type])));
+                return 0;
+            }
+            case 'get': {
+                need(rest, 1, 'qsys get <name...>');
+                const controls = await client.getControl(rest);
+                printControls(io, controls, json);
+                return 0;
+            }
+            case 'set': {
+                need(rest, 2, 'qsys set <name> <value> [--ramp <s>]');
+                const [name, raw] = rest;
+                await client.setControl(name, coerceValue(raw), numFlag(flags.ramp, 'ramp'));
+                printControls(io, await client.getControl([name]), json); // echo the readback
+                return 0;
+            }
+            case 'get-component': {
+                need(rest, 1, 'qsys get-component <comp> [ctrl...]');
+                const [comp, ...ctrls] = rest;
+                const r = ctrls.length > 0
+                    ? await client.getComponent(comp, ctrls)
+                    : await client.getComponentControls(comp);
+                printControls(io, r.Controls, json);
+                return 0;
+            }
+            case 'set-component': {
+                need(rest, 3, 'qsys set-component <comp> <ctrl> <value> [--ramp <s>]');
+                const [comp, ctrl, raw] = rest;
+                await client.setComponent(comp, [
+                    { Name: ctrl, Value: coerceValue(raw), Ramp: numFlag(flags.ramp, 'ramp') },
+                ]);
+                printControls(io, (await client.getComponent(comp, [ctrl])).Controls, json);
+                return 0;
+            }
+            case 'snapshot': {
+                need(rest, 3, 'qsys snapshot <load|save> <bank> <slot>');
+                const [sub, bank, slotRaw] = rest;
+                const slot = Number(slotRaw);
+                if (!Number.isInteger(slot))
+                    throw new UsageError(`invalid snapshot slot: ${slotRaw}`);
+                if (sub === 'load')
+                    await client.snapshotLoad(bank, slot, numFlag(flags.ramp, 'ramp'));
+                else if (sub === 'save')
+                    await client.snapshotSave(bank, slot);
+                else
+                    throw new UsageError(`unknown snapshot subcommand: ${sub}`);
+                io.out(`snapshot ${sub}: ${bank} #${slot}`);
+                return 0;
+            }
+            case 'watch':
+                return await watch(client, rest, flags, json, io);
+            default:
+                throw new UsageError(`unknown command: ${cmd}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            io.err(`qsys: ${err.message}`);
+            io.err(USAGE);
+            return 2;
+        }
+        io.err(`qsys: ${err.message}`);
+        return 1;
+    }
+    finally {
+        client.close();
+    }
+}
+function printControls(io, controls, json) {
+    if (json)
+        io.out(JSON.stringify(controls, null, 2));
+    else
+        io.out(renderTable(CONTROL_HEADER, controls.map(controlRow)));
+}
+/**
+ * Change-group stream: register the controls, print current values, then let
+ * the Core push changes via ChangeGroup.AutoPoll until the abort signal fires.
+ */
+async function watch(client, names, flags, json, io) {
+    need(names, 1, 'qsys watch [--component <comp>] <ctrl...>');
+    const component = flags.component;
+    const interval = numFlag(flags.interval, 'interval') ?? 0.5;
+    const id = `qsys-cli-${process.pid}`;
+    if (component)
+        await client.changeGroupAddComponentControl(id, component, names);
+    else
+        await client.changeGroupAddControl(id, names);
+    const emit = (c) => {
+        if (json)
+            io.out(JSON.stringify(c));
+        else
+            io.out(`${new Date().toISOString().slice(11, 23)}  ${controlRow(c).join('  ').trimEnd()}`);
+    };
+    // First poll returns current values — the baseline before the stream starts.
+    for (const c of (await client.changeGroupPoll(id)).Changes)
+        emit(c);
+    await client.send('ChangeGroup.AutoPoll', { Id: id, Rate: interval });
+    const onNotification = (msg) => {
+        if (msg.method !== 'ChangeGroup.Poll' || msg.params?.Id !== id)
+            return;
+        for (const c of msg.params.Changes ?? [])
+            emit(c);
+    };
+    client.on('notification', onNotification);
+    await new Promise((resolve) => {
+        if (io.signal) {
+            // Only the abort signal ends the stream — a socket drop just reconnects.
+            if (io.signal.aborted)
+                return resolve();
+            io.signal.addEventListener('abort', () => resolve(), { once: true });
+        }
+        else {
+            // No signal (programmatic use): stream until the caller closes the client.
+            client.once('close', () => resolve());
+        }
+    });
+    client.off('notification', onNotification);
+    if (client.isConnected())
+        await client.changeGroupDestroy(id).catch(() => { });
+    return 0;
+}

package/dist/format.d.ts

@@ -0,0 +1,17 @@
+import type { ControlValue, QrcControl } from 'qsys-qrc';
+/** A poll/get row; change-group polls tag component controls with their owner. */
+export type ControlRow = QrcControl & {
+    Component?: string;
+};
+export declare const CONTROL_HEADER: string[];
+export declare function controlRow(c: ControlRow): string[];
+export declare function fmtValue(v: ControlValue | undefined): string;
+/** Right-pad cells so columns align. No wrapping — terminals scroll. */
+export declare function renderTable(header: string[], rows: string[][]): string;
+/** Two-column key/value block (status output). */
+export declare function renderKv(pairs: Array<[string, string]>): string;
+/**
+ * CLI arg → QRC control value: `true`/`false` → boolean, numeric → number,
+ * anything else stays a string (e.g. a combo-box item name).
+ */
+export declare function coerceValue(raw: string): ControlValue;

package/dist/format.js

@@ -0,0 +1,47 @@
+export const CONTROL_HEADER = ['NAME', 'VALUE', 'STRING', 'POSITION'];
+export function controlRow(c) {
+    return [
+        c.Component ? `${c.Component}.${c.Name}` : c.Name,
+        fmtValue(c.Value),
+        c.String ?? '',
+        c.Position == null ? '' : c.Position.toFixed(3),
+    ];
+}
+export function fmtValue(v) {
+    if (v === undefined)
+        return '';
+    if (typeof v === 'number' && !Number.isInteger(v)) {
+        return String(Number(v.toFixed(4)));
+    }
+    return String(v);
+}
+/** Right-pad cells so columns align. No wrapping — terminals scroll. */
+export function renderTable(header, rows) {
+    const all = header.length > 0 ? [header, ...rows] : rows;
+    const cols = Math.max(...all.map((r) => r.length));
+    const widths = [];
+    for (let c = 0; c < cols; c++) {
+        widths.push(Math.max(...all.map((r) => (r[c] ?? '').length)));
+    }
+    return all
+        .map((r) => r.map((cell, c) => (cell ?? '').padEnd(widths[c])).join('  ').trimEnd())
+        .join('\n');
+}
+/** Two-column key/value block (status output). */
+export function renderKv(pairs) {
+    return renderTable([], pairs.map(([k, v]) => [k, v]));
+}
+/**
+ * CLI arg → QRC control value: `true`/`false` → boolean, numeric → number,
+ * anything else stays a string (e.g. a combo-box item name).
+ */
+export function coerceValue(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    const n = Number(raw);
+    if (raw.trim() !== '' && Number.isFinite(n))
+        return n;
+    return raw;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** qsys — control CLI over QrcClient; runCli is exported for embedding/tests. */
+export { runCli, parseCliArgs, UsageError, USAGE, type CliIo } from './cli.js';
+export * from './format.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+/** qsys — control CLI over QrcClient; runCli is exported for embedding/tests. */
+export { runCli, parseCliArgs, UsageError, USAGE } from './cli.js';
+export * from './format.js';

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "qsys-cli",
+  "version": "0.1.0",
+  "description": "Human/scriptable CLI to control a Q-SYS Core over QRC — status, component inventory, get/set controls, watch, snapshots.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "qsys": "dist/bin.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "postbuild": "node -e \"require('fs').chmodSync('dist/bin.js', 0o755)\"",
+    "prepare": "npm run build",
+    "qsys": "tsx src/bin.ts --",
+    "test": "node ../../scripts/run-if-emulator.mjs \"tsx test/cli.ts\""
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reowens/qsys-tools.git",
+    "directory": "packages/qsys"
+  },
+  "bugs": {
+    "url": "https://github.com/reowens/qsys-tools/issues"
+  },
+  "homepage": "https://github.com/reowens/qsys-tools/tree/main/packages/qsys#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": [
+    "q-sys",
+    "qsys",
+    "qsc",
+    "qrc",
+    "cli",
+    "av"
+  ],
+  "dependencies": {
+    "qsys-qrc": "^0.1.0"
+  }
+}