CLI Reference

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 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 or a Node installer.

Then install the CLI globally using npm:

npm i -g @quantum-hub/qhubctl

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

qhubctl help

You may also get information about a specific command:

qhubctl help <command>

# or
qhubctl <command> --help

Authentication

Please copy your personal access token to your clipboard.

Login to your account using your access token:

qhubctl login -t <your access token>

Overview

qhubctl <command> [options]

Command	Description
qhubctl 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	Upload files to a data pool
qhubctl get-context	Get the current context, i.e., the personal or organization account you are currently working with
qhubctl init	Bootstrap project to create a service
qhubctl list-contexts	Retrieves the available contexts, i.e., the personal or organizational accounts available to you to work with
qhubctl login	Login with your credentials
qhubctl logout	Logout
qhubctl 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	Creates a job execution
qhubctl 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-status	Show the build status of a service
qhubctl services list	List all services of the current context
qhubctl set-context	Set the current context, i.e., the personal or organization account you are currently working with
qhubctl 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 ...] [--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).
--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-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.