---
url: /cli-reference.md
description: >-
  Install and use qhubctl to authenticate, bootstrap projects, run services
  locally, and deploy them to Kipu Quantum Hub from the terminal.
---

# CLI Reference

> \[!INFO] At a glance
>
> * **Purpose:**
>   Terminal tool for the project lifecycle on Kipu Quantum Hub — log in, bootstrap a service, run it locally, deploy it, upload data pool files, inspect builds.
> * **Package:** `@quantum-hub/qhubctl` *(Node.js 20+, installed globally via npm)*
> * **Binary:** `qhubctl`
> * **Use it when:** you develop and deploy your own Managed Service, or want a one-shot way to authenticate once for all SDKs.
> * **Pairs with:**
>   `qhubctl login` stores the personal access token used automatically by the [Quantum SDK](/sdk-quantum).
>   Service settings are configured via [`qhub.json`](/qhub-json-reference).
> * **Quick reference:** `qhubctl help` · `qhubctl help <command>` · `qhubctl <command> --help`
> * **New here?** See the [References Overview](/references/).

The Command Line Interface (CLI) lets you interact with the Kipu Quantum Hub directly from your terminal.
We have installation instructions to guide you through the initial setup in our [quickstart](quickstart) guide.

## Installation

To install the CLI, you must install **Node.js 20** or higher and the npm command line interface using either a
[Node version manager](https://github.com/nvm-sh/nvm) or a [Node installer](https://nodejs.org/en/download).

Then install the CLI globally using npm:

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

You can use the `help` command to get information about the supported commands:

```bash
qhubctl help
```

You may also get information about a specific command:

```bash
qhubctl help <command>

# or
qhubctl <command> --help
```

## Authentication

Please copy your [personal access token](https://dashboard.hub.kipu-quantum.com) to your clipboard.

Login to your account using your access token:

```bash
qhubctl login -t <your access token>
```

## Overview

```
qhubctl <command> [options]
```

| Command                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                    |
|-----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`qhubctl compress`](#compress)                           | Compresses the current project and creates a ZIP file. Use the '.dockerignore' file to exclude files and directories from the ZIP file                                                                                                                                                                                                                                                                                                         |
| [`qhubctl datapool upload`](#datapool-upload)             | Upload files to a data pool                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [`qhubctl get-context`](#get-context)                     | Get the current context, i.e., the personal or organization account you are currently working with                                                                                                                                                                                                                                                                                                                                             |
| [`qhubctl init`](#init)                                   | Bootstrap project to create a service                                                                                                                                                                                                                                                                                                                                                                                                          |
| [`qhubctl list-contexts`](#list-contexts)                 | Retrieves the available contexts, i.e., the personal or organizational accounts available to you to work with                                                                                                                                                                                                                                                                                                                                  |
| [`qhubctl login`](#login)                                 | Login with your credentials                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [`qhubctl logout`](#logout)                               | Logout                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [`qhubctl openapi`](#openapi)                             | Generates the OpenAPI description for your project based on the parameter and return types of your run() method. The output of this command will be used when creating or updating your service. Supports PYTHON\_TEMPLATE (with src/program.py), PYTHON and DOCKER runtimes (with explicit entrypoint). Requires uv and a valid uv project in the workspace. The "qhub-commons" dependency is installed/upgraded automatically as a dependency |
| [`qhubctl run`](#run)                                     | Creates a job execution                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [`qhubctl serve`](#serve)                                 | Runs your project locally via qhub-serve inside the workspace virtual environment, exposing the same HTTP endpoints as Kipu Quantum Hub (start execution, check status, cancel, retrieve results)                                                                                                                                                                                                                                              |
| [`qhubctl services build-logs`](#services-build-logs)     | Show the build logs of a service                                                                                                                                                                                                                                                                                                                                                                                                               |
| [`qhubctl services build-status`](#services-build-status) | Show the build status of a service                                                                                                                                                                                                                                                                                                                                                                                                             |
| [`qhubctl services list`](#services-list)                 | List all services of the current context                                                                                                                                                                                                                                                                                                                                                                                                       |
| [`qhubctl set-context`](#set-context)                     | Set the current context, i.e., the personal or organization account you are currently working with                                                                                                                                                                                                                                                                                                                                             |
| [`qhubctl up`](#up)                                       | Creates or updates a service                                                                                                                                                                                                                                                                                                                                                                                                                   |

## compress

Compresses the current project and creates a ZIP file. Use the '.dockerignore' file to exclude files and directories from the ZIP file.

**Usage**

```
qhubctl compress
```

## datapool upload

Upload files to a data pool

**Usage**

```
qhubctl datapool upload --file ... [--datapool-id ...]
```

**Options**

| Flag                        | Required | Default | Description                                                                                             |
|-----------------------------|----------|---------|---------------------------------------------------------------------------------------------------------|
| `-f, --file <value...>`     | yes      | —       | Path to a file to upload (can be specified multiple times)                                              |
| `-d, --datapool-id <value>` | no       | —       | ID of the data pool to upload the files to (optional - will prompt to create a new one if not provided) |

## get-context

Get the current context, i.e., the personal or organization account you are currently working with.

**Usage**

```
qhubctl get-context
```

## init

Bootstrap project to create a service.

**Usage**

```
qhubctl init [--name ...] [--non-interactive]
```

**Options**

| Flag                | Required | Default | Description                    |
|---------------------|----------|---------|--------------------------------|
| `--name <value>`    | no       | —       | The name of the service        |
| `--non-interactive` | no       | —       | Run it in non-interactive mode |

## list-contexts

Retrieves the available contexts, i.e., the personal or organizational accounts available to you to work with.

**Usage**

```
qhubctl list-contexts
```

## login

Login with your credentials

**Usage**

```
qhubctl login [--token ...] [--base-path ...]
```

**Options**

| Flag                  | Required | Default | Description                                       |
|-----------------------|----------|---------|---------------------------------------------------|
| `-t, --token <value>` | no       | —       | Your personal access token                        |
| `--base-path <value>` | no       | —       | Custom base path for authentication (development) |

## logout

Logout

**Usage**

```
qhubctl logout
```

## openapi

Generates the OpenAPI description for your project based on the parameter and return types of your run() method. The output of this command will be used when creating or updating your service. Supports PYTHON\_TEMPLATE (with src/program.py), PYTHON and DOCKER runtimes (with explicit entrypoint). Requires uv and a valid uv project in the workspace. The "qhub-commons" dependency is installed/upgraded automatically as a dependency.

**Usage**

```
qhubctl openapi [--force] [--file ...] [--format ...] [--entrypoint ...] [--package ...] [--method ...]
```

**Options**

| Flag                   | Required | Default | Description                                                                                                                              |
|------------------------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------|
| `-f, --force`          | no       | —       | Overwrite the output file if it already exists                                                                                           |
| `--file <value>`       | no       | —       | The file to write the OpenAPI description to                                                                                             |
| `--format <value>`     | no       | —       | The format to generate the OpenAPI description \[possible values: yaml]                                                                   |
| `--entrypoint <value>` | no       | —       | The entrypoint to your program in the format "package.module:function" (default: "src.program:run"). Overrides package and method flags. |
| `--package <value>`    | no       | —       | The package/module path to your program (e.g., "src.program" or "my\_package.main"). Only used if entrypoint is not provided.             |
| `--method <value>`     | no       | —       | The method/function name in your program (default: "run"). Only used if entrypoint is not provided.                                      |

## run

Creates a job execution

**Usage**

```
qhubctl run [<serviceId>] [--input ...] [--input-files ...] [--store-input] [--tag ...] [--detached]
```

**Arguments**

| Argument      | Required | Description                                                               |
|---------------|----------|---------------------------------------------------------------------------|
| `<serviceId>` | no       | The ID of the service to run (optional — reads from qhub.json if omitted) |

**Options**

| Flag                    | Required | Default | Description                                                                                                    |
|-------------------------|----------|---------|----------------------------------------------------------------------------------------------------------------|
| `-i, --input <value>`   | no       | —       | Input as JSON string.                                                                                          |
| `--input-files <value>` | no       | —       | Comma-separated paths to files containing input to be merged (default: ./input/data.json,./input/params.json). |
| `--store-input`         | no       | —       | Persist the input data alongside the job on the server.                                                        |
| `--tag <value>`         | no       | \`\`      | Tag to attach to the job. Repeat the flag to attach multiple tags.                                             |
| `--detached`            | no       | —       | Executes the job in detached mode, i.e., without waiting for it to finish.                                     |

## serve

Runs your project locally via qhub-serve inside the workspace virtual environment, exposing the same HTTP endpoints as Kipu Quantum Hub (start execution, check status, cancel, retrieve results).

**Usage**

```
qhubctl serve [--port ...] [--log-level ...] [--workspace ...]
```

**Options**

| Flag                     | Required | Default | Description                                                                                      |
|--------------------------|----------|---------|--------------------------------------------------------------------------------------------------|
| `-p, --port <number>`    | no       | `8081`  | The port on which the local web server accepts requests                                          |
| `--log-level <level>`    | no       | `INFO`  | Log level for qhub-serve. Possible values: TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL |
| `-w, --workspace <path>` | no       | —       | Path to the workspace directory (must be a valid uv project). Defaults to the current directory. |

## services build-logs

Show the build logs of a service.

**Usage**

```
qhubctl services build-logs [--id ...] [--json]
```

**Options**

| Flag           | Required | Default | Description                                             |
|----------------|----------|---------|---------------------------------------------------------|
| `--id <value>` | no       | —       | The ID of the service (reads from qhub.json if omitted) |
| `--json`       | no       | —       | Output in JSON format                                   |

## services build-status

Show the build status of a service.

**Usage**

```
qhubctl services build-status [--id ...] [--json]
```

**Options**

| Flag           | Required | Default | Description                                             |
|----------------|----------|---------|---------------------------------------------------------|
| `--id <value>` | no       | —       | The ID of the service (reads from qhub.json if omitted) |
| `--json`       | no       | —       | Output in JSON format                                   |

## services list

List all services of the current context.

**Usage**

```
qhubctl services list [--json] [--name ...] [--all]
```

**Options**

| Flag             | Required | Default | Description                                                 |
|------------------|----------|---------|-------------------------------------------------------------|
| `--json`         | no       | —       | Output in JSON format                                       |
| `--name <value>` | no       | —       | Filter services by name (case-insensitive full match)       |
| `--all`          | no       | —       | Display all service properties (only available with --json) |

## set-context

Set the current context, i.e., the personal or organization account you are currently working with.

**Usage**

```
qhubctl set-context [<contextId>]
```

**Arguments**

| Argument      | Required | Description                        |
|---------------|----------|------------------------------------|
| `<contextId>` | no       | The ID of the context to switch to |

## up

Creates or updates a service

**Usage**

```
qhubctl up [--silent] [--no-save-id] [--name ...]
```

**Options**

| Flag             | Required | Default | Description                                                        |
|------------------|----------|---------|--------------------------------------------------------------------|
| `--silent`       | no       | —       | Suppresses all outputs, helpful when executed in a CI/CD pipeline. |
| `--no-save-id`   | no       | —       | Prevents storing the created service ID in qhub.json file.         |
| `--name <value>` | no       | —       | Override the service name from qhub.json with a custom name.       |