CLI Reference

Generated from @quantum-hub/qhubctl@2.1.0. Run npm run docs:generate to update.

Overview

qhubctl <command> [options]

Command	Description
qhubctl compress	Compresses the current project and creates a ZIP file. Use a '.qhubignore' file (gitignore syntax) 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) and DOCKER runtime (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-logs	Show the build logs of a service
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 a '.qhubignore' file (gitignore syntax) to exclude files and directories from the ZIP file.

.git, node_modules, .venv, __pycache__, and service.zip are always excluded. Because .qhubignore uses gitignore syntax, re-including a directory's contents requires both the directory and its contents — for example, to ship only src and the Dockerfile:

*
!src
!src/**
!Dockerfile

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) and DOCKER runtime (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.

Use a '.qhubignore' file (gitignore syntax) to exclude files and directories from the ZIP file.

.git, node_modules, .venv, __pycache__, and service.zip are always excluded. Because .qhubignore uses gitignore syntax, re-including a directory's contents requires both the directory and its contents — for example, to ship only src and the Dockerfile:

*
!src
!src/**
!Dockerfile

Usage

qhubctl up [--silent] [--no-save-id] [--name ...] [--image ...] [--registry-username ...] [--registry-password ...]

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.
--image <ref>	no	—	Deploy a pre-built image from a container registry, given as registry/repo:tag (the tag defaults to "latest").
--registry-username <value>	no	—	Username to pull a private registry image. Falls back to the QHUB_REGISTRY_USERNAME environment variable.
--registry-password <value>	no	—	Password to pull a private registry image. Falls back to the QHUB_REGISTRY_PASSWORD environment variable.