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

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.90.225.20.nip.io -t <personal access token>

Debug output

Set DEBUG=* to print all debug output:

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

On Windows, set the variable separately:

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

Tests

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

Lint

npm run lint

Generate docs

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

npm run build
npm run docs:generate

Regenerating the API client

The generated clients in src/client/ are produced from the platform OpenAPI specs using openapi-generator-cli.

npm install -g @openapitools/openapi-generator-cli

Against production:

openapi-generator-cli generate -g typescript-fetch \
  -i https://api.hub.kipu-quantum.com/qc-catalog/docs \
  -o src/client/kqh

openapi-generator-cli generate -g typescript-fetch \
  -i https://api.hub.kipu-quantum.com/user-service/docs \
  -o src/client/users

Against staging:

openapi-generator-cli generate -g typescript-fetch \
  -i https://api.hub.34.90.225.20.nip.io/qc-catalog/docs \
  -o src/client/kqh

openapi-generator-cli generate -g typescript-fetch \
  -i https://api.hub.34.90.225.20.nip.io/user-service/docs \
  -o src/client/users

License

Apache-2.0 | Copyright 2026-now Kipu Quantum GmbH