qhubctl

qhubctl, is a Command Line Interface (CLI) which lets you interact with the Kipu Quantum Hub from your terminal.

Detailed information about the supported commands can be found in our CLI reference.

Installation

Node.js 20 or higher is required. Install it via a Node version manager or a Node installer.

npm install -g @quantum-hub/qhubctl

To try the newest prerelease instead, install from the next dist-tag:

npm install -g @quantum-hub/qhubctl@next

Troubleshooting: If you see EACCES permissions errors, use nvm or see the npm docs.

Usage

qhubctl --help
qhubctl <command> --help

Development

Build

npm install
npm run build

Compiles TypeScript from src/ to dist/. The CLI entry point is dist/main.js.

Run locally

node dist/main.js <command>

Watch mode

For active development, run the TypeScript compiler in watch mode so every file save triggers an incremental rebuild:

npm run dev

qhubctl will reflect your latest changes on the next invocation without any manual rebuild step.

Linking globally with npm link

npm link registers a global qhubctl symlink that points permanently to dist/main.js in your local checkout. Run it once after the initial setup:

npm run build
npm link
qhubctl <command>   # now resolves to your local build

The symlink persists across rebuilds and watch-mode recompiles — you never need to run npm link again unless you delete and re-clone the repo or change the "bin" entry in package.json.

Note: npm link and a globally installed published version of qhubctl are mutually exclusive — they occupy the same path. The last one to run wins. Use which qhubctl or qhubctl --version to confirm which is currently active.

To switch back to the published version from npm:

npm unlink -g @quantum-hub/qhubctl   # removes the local symlink
npm install -g @quantum-hub/qhubctl  # installs the published version

To go back to your local dev version:

npm link

Run against staging

node dist/main.js login --base-path https://api.hub.34.6.228.233.nip.io -t <personal access token>

Debug output

Set DEBUG=1 to print all debug output:

DEBUG=1 node dist/main.js <command>

# or
DEBUG=1 qhubctl <command>

On Windows, set the variable separately:

set DEBUG=1
node dist\main.js <command>

Tests

npm test                    # run tests + lint
npm run test:coverage       # run tests with lcov coverage report

Lint and format

npm run lint          # eslint + prettier --check
npm run lint:code:fix # eslint --fix
npm run format        # prettier --write

Generate docs

Produces a Markdown CLI reference at docs/cli-reference.md from the compiled program:

npm run build
npm run docs:generate

Releasing

There are two paths, and the version always comes from the Git tag — the version in package.json is the placeholder 0.0.0-development and is never bumped (see ADR 0003). So qhubctl --version from a local build prints the placeholder.

Prereleases publish automatically, with no review. Every feat/fix/perf commit on main publishes a *-next.* version under the next dist-tag.

Final releases are gated. Open a merge request from main to the protected release branch; merging it publishes the final version under latest. The merge must fast-forward — a merge commit hides the release tag from main and breaks prerelease numbering.

The prerelease number is a build counter, not a forecast. Once a prerelease series opens, later commits only increment the counter; the base version never rises. 2.2.2-next.2 can ship as 2.3.0, leaving a prerelease series on npm with no matching final release.

License

Apache-2.0 | Copyright 2026-now Kipu Quantum GmbH