npm package: @quantum-hub/qhubctl
Description: Kipu Quantum Hub CLI
Author: Kipu Quantum GmbH
Latest version: 1.9.0

# 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](https://docs.hub.kipu-quantum.com/cli-reference.html).

## Installation

Node.js 20 or higher is required.
Install it via a [Node version manager](https://github.com/nvm-sh/nvm) or a [Node installer](https://nodejs.org/en/download).

```bash
npm install -g @quantum-hub/qhubctl
```

> **Troubleshooting:** If you see `EACCES permissions` errors, use [nvm](https://github.com/nvm-sh/nvm) or see the [npm docs](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).

## Usage

```bash
qhubctl --help
qhubctl <command> --help
```

## Development

### Build

```bash
npm install
npm run build
```

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

### Run locally

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
npm link
```

### Run against staging

```bash
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:

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

On Windows, set the variable separately:

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

### Tests

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

### Lint

```bash
npm run lint
```

### Generate docs

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

```bash
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](https://github.com/OpenAPITools/openapi-generator-cli).

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

Against production:

```bash
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:

```bash
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](https://www.apache.org/licenses/LICENSE-2.0) | Copyright 2026-now Kipu Quantum GmbH