Skip to content
Quantum Helix

QHx CLI Reference

Use qhx to inspect HTTP and MQTT notarization data, manage federation and licenses, and install QHx. Use kubectl for Kubernetes resource operations.

Start with Install the QHx CLI. To check the installed version and inspect a command:

Terminal window
qhx --version
qhx --help
qhx curl --help

The command help below lists usage, flags, and defaults. Commands and help wording can vary by release. Check qhx --version and the installed command’s --help before using an example with your installation. For an older binary without --version, identify its release from the installed artifact and use its available help.

Configuration and logging

Section titled “Configuration and logging”

Select Kubernetes credentials with your kubeconfig. install and individual federation commands accept --kubeconfig; federation commands also accept --context where shown in their help. License commands use the standard Kubernetes configuration, including KUBECONFIG.

Global logging and SPIFFE socket options appear in root help. --debug and --log-devel both enable development logging. An explicit --verbose value takes precedence over their default verbosity; contradictory values for the two development-logging flags are rejected.

The installer supports QHX_CUSTOMER_DEPLOYMENT_USERNAME and QHX_CUSTOMER_DEPLOYMENT_PASSWORD. See the installation guide for credential precedence and Docker/OCI credential discovery.

HTTP requests

Section titled “HTTP requests”

qhx curl accepts one URL and the flags listed in its help. For a local HTTP service listening on port 8080 that does not return QHx headers:

Terminal window
qhx curl --validate=false http://127.0.0.1:8080/health
qhx curl --validate=false -X POST -H 'Content-Type: application/json' \
  -d '{"message":"hello"}' http://127.0.0.1:8080/echo
qhx curl --validate=false --silent --show-headers http://127.0.0.1:8080/health

For QHx-protected services, see the notarization guide and AI chat example. HTTP behavior to account for when scripting:

  • Validation is required by default. --validate=false permits a response without a workload statement and skips receipt verification; a workload statement that is present is still verified. Verification needs access to the configured SPIFFE Workload API and the service’s notary endpoints.
  • Nonempty --data changes the request method from GET to POST, including when GET was explicitly selected. Set a content-type header for JSON data.
  • The response body goes to standard output. --silent suppresses that body; it does not suppress --show-headers, errors, or printed artifacts.
  • --print-workload and --print-receipt write human-readable reports to standard error. They do not export standalone JSON or signed receipt files. HTTP receipt printing requires signRequest with validation enabled.
  • A command error exits with status 1; success exits with status 0. HTTP 4xx or 5xx status codes alone do not cause a command error. Inspect the status with --show-headers when needed.

MQTT artifact inspection

Section titled “MQTT artifact inspection”

Pass an mqtt:// or mqtts:// URL to qhx curl to subscribe to $.qhx/workload/# and $.qhx/receipt/#. Supply an explicit port and at least one print flag:

Terminal window
qhx curl --print-workload --print-receipt mqtt://127.0.0.1:1883

This example requires a reachable MQTT broker carrying QHx notary artifacts. The command waits for messages until the connection closes or you interrupt it. mqtts:// uses TLS with system trust. MQTT artifacts are decoded and printed to standard error without signature verification. HTTP options such as --validate and --notarization-level do not change MQTT inspection. Use an MQTT publishing client to send application messages; qhx curl only subscribes to the artifact topics.

Federation, licenses, and installation

Section titled “Federation, licenses, and installation”
  • qhx federation exposes connection, export/import, and artifact inspection commands. federation info reports information about the selected cluster. Commands use the Kubernetes contexts indicated by their flags; federation inspect bootstrap-package inspects a local file. Follow Federation Setup to connect clusters and check the resulting relationship.
  • qhx license inspects a signed file with info FILE, installs it with install FILE, and reads cluster status with status. license install --dry-run FILE verifies the file and prints the Secret YAML without creating it. A signed license file is required; cluster operations also require Kubernetes access.
  • qhx install provides the wizard and online, download, and offline modes. Follow Install using QHx CLI for prerequisites and complete workflows. Root qhx --version prints the CLI version; qhx install --version VERSION selects the release to install.

Command help

Section titled “Command help”

qhx

Section titled “qhx”
$ qhx --help
QHx CLI provides tools for interacting with quantum-safe attestation infrastructure.


Usage:
  qhx [command]


Available Commands:
  curl        Make HTTP requests
  federation  Establish and manage inter-cluster QHx federation
  help        Help about any command
  install     Install QHx on a ready Kubernetes cluster
  license     Inspect and manage QHx licenses


Flags:
      --debug                       Enable verbose development logging
  -h, --help                        help for qhx
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)
      --version                     version for qhx


Use "qhx [command] --help" for more information about a command.

qhx curl

Section titled “qhx curl”
$ qhx curl --help
Make HTTP requests using a curl-esque interface.


Usage:
  qhx curl [flags] <url>


Flags:
  -d, --data string                 HTTP POST data
  -H, --header stringArray          custom header to include in request
  -h, --help                        help for curl
      --inject-faults strings       inject faults (supported: no-workload-statement, bad-workload-statement)
  -n, --notarization-level string   notarization level (workload, logRequest, signRequest) (default "workload")
      --print-receipt               pretty-print signed request receipt when successfully validated (signRequest level only)
      --print-workload              pretty-print workload identity statement when successfully validated
  -X, --request string              request method (default "GET")
  -i, --show-headers                show response headers in output
  -s, --silent                      silent mode
      --validate                    require workload statement verification (default true)


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)

qhx federation

Section titled “qhx federation”
$ qhx federation --help
Establish and manage inter-cluster QHx federation


Usage:
  qhx federation [command]


Available Commands:
  connect     Establish federation between two QHx clusters
  export      Export federation artifacts for offline transfer
  import      Import federation artifacts from offline transfer
  info        Print this cluster's self-authenticating federation reference
  inspect     Inspect federation artifacts


Flags:
  -h, --help   help for federation


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)


Use "qhx federation [command] --help" for more information about a command.

qhx federation connect

Section titled “qhx federation connect”
$ qhx federation connect --help
Configure federation using a peer's bootstrap reference or two kubeconfigs.


With a bootstrap reference, the cluster selected by your kubeconfig and context
is configured to trust that peer:
  qhx federation connect -K selected.kubeconfig "$PEER_REFERENCE"


With two kubeconfigs, both clusters are configured to trust each other:
  qhx federation connect -K selected.kubeconfig -K peer.kubeconfig


Add --unidirectional to configure only the first cluster to trust the second.


The CLI records the relationship. The QHx Manager in each receiving cluster
fetches and verifies the peer's bootstrap package. With two kubeconfigs, the CLI
first reads both packages through Kubernetes port-forwarding to obtain their
fingerprints and trust domains.


Your host needs Kubernetes API access to the selected cluster, or API and
port-forward access to both clusters when using two kubeconfigs. Each receiving
manager needs access to its peer's M2M endpoint.


Bootstrap completes asynchronously. Check QHxForeignCluster status in each
receiving cluster.


Usage:
  qhx federation connect [reference] [flags]


Flags:
      --context stringArray      Kubeconfig context (positional with --kubeconfig)
  -h, --help                     help for connect
  -K, --kubeconfig stringArray   Kubeconfig path (repeat for dual-cluster connect)
      --unidirectional           Create only the first→second relationship


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)

qhx federation export

Section titled “qhx federation export”
$ qhx federation export --help
Export federation artifacts for offline transfer


Usage:
  qhx federation export [command]


Available Commands:
  bootstrap-package Export this cluster's bootstrap package to a file


Flags:
  -h, --help   help for export


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)


Use "qhx federation export [command] --help" for more information about a command.

qhx federation export bootstrap-package

Section titled “qhx federation export bootstrap-package”
$ qhx federation export bootstrap-package --help
Export this cluster's bootstrap package to a file


Usage:
  qhx federation export bootstrap-package [flags]


Flags:
      --context string         Kubeconfig context to use
      --endpoint-host string   M2M endpoint host[:port] to advertise as an unsigned routing hint (default: discover the NodePort endpoint)
  -f, --file string            Output file path (required)
  -h, --help                   help for bootstrap-package
  -K, --kubeconfig string      Path to the kubeconfig file


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)

qhx federation import

Section titled “qhx federation import”
$ qhx federation import --help
Import federation artifacts from offline transfer


Usage:
  qhx federation import [command]


Available Commands:
  bootstrap-package Import a peer's bootstrap package and create a QHxForeignCluster


Flags:
  -h, --help   help for import


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)


Use "qhx federation import [command] --help" for more information about a command.

qhx federation import bootstrap-package

Section titled “qhx federation import bootstrap-package”
$ qhx federation import bootstrap-package --help
Import a peer's bootstrap package and create a QHxForeignCluster


Usage:
  qhx federation import bootstrap-package [flags]


Flags:
      --context string              Kubeconfig context to use
      --expect-fingerprint string   Optionally assert the package's fingerprint; the import fails if it does not match. The package's authenticity is otherwise anchored by the administrator's vetting of the file
  -f, --file string                 Bootstrap package file path (required)
      --force-rebootstrap           Replace the relationship even if M2M continuity still works
  -h, --help                        help for bootstrap-package
  -K, --kubeconfig string           Path to the kubeconfig file
      --m2m-endpoint string         Peer M2M endpoint host[:port] hint for steady-state polling (a leading https:// is accepted and stripped)
      --name string                 QHxForeignCluster object name (defaults to the peer trust domain label)
      --rebootstrap                 Reset a relationship whose continuity is broken, expired, or unverifiable


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)

qhx federation info

Section titled “qhx federation info”
$ qhx federation info --help
Print this cluster's self-authenticating federation reference


Usage:
  qhx federation info [flags]


Flags:
      --context string         Kubeconfig context to use
      --endpoint-host string   M2M endpoint host[:port] to advertise (default: discover the NodePort endpoint)
  -h, --help                   help for info
  -K, --kubeconfig string      Path to the kubeconfig file
      --tunnel                 Read the live bootstrap package over the M2M endpoint via port-forward instead of QHxCluster.status


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)

qhx federation inspect

Section titled “qhx federation inspect”
$ qhx federation inspect --help
Inspect federation artifacts


Usage:
  qhx federation inspect [command]


Available Commands:
  bootstrap-package Decode a bootstrap package and print all of its contents as YAML


Flags:
  -h, --help   help for inspect


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)


Use "qhx federation inspect [command] --help" for more information about a command.

qhx federation inspect bootstrap-package

Section titled “qhx federation inspect bootstrap-package”
$ qhx federation inspect bootstrap-package --help
Decode a bootstrap package and print all of its contents as YAML


Usage:
  qhx federation inspect bootstrap-package [flags]


Flags:
  -f, --file string   Bootstrap package file path (required)
      --full          Show full certificate chains and signatures instead of eliding them
  -h, --help          help for bootstrap-package


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)

qhx help

Section titled “qhx help”
$ qhx help --help
Help provides help for any command in the application.
Simply type qhx help [path to command] for full details.


Usage:
  qhx help [command] [flags]


Flags:
  -h, --help   help for help


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)

qhx install

Section titled “qhx install”
$ qhx install --help
Install QHx on a ready Kubernetes cluster


Usage:
  qhx install [flags]


Flags:
      --download                    Download an air-gapped release package
  -n, --dry-run                     render without modifying the cluster or mirror
  -f, --file string                 release package input or output path
  -h, --help                        help for install
  -K, --kubeconfig string           KUBECONFIG file for the target cluster
      --kubernetes-variant string   Kubernetes variant override for online/offline installs; package downloads remain variant-neutral (accepted: eks, kind, microk8s, openshift, unknown; default: detect cluster, falling back to unknown)
      --mirror-ca-file string       PEM CA certificate bundle for the HTTPS mirror registry
  -I, --mirror-insecure             use HTTP for the mirror registry
  -p, --mirror-password string      mirror registry password
  -r, --mirror-registry string      air-gap mirror registry hostname
  -u, --mirror-username string      mirror registry username
      --offline-install             Install an air-gapped release package
      --online                      Perform an online install
      --platform string             comma-separated platforms (default: all release platforms)
      --qhx-ca-file string          PEM CA certificate bundle for the HTTPS QHx registry
      --qhx-insecure                use HTTP for the QHx registry
  -P, --qhx-password string         QHx customer deployment key password
  -R, --qhx-registry string         QHx registry host[:port][/repository-prefix] (default "oci.messier42.com")
  -U, --qhx-username string         QHx customer deployment key username
      --set stringArray             set a supported Helm value (repeatable)
      --set-string stringArray      set a supported Helm string value (repeatable)
      --timeout duration            Helm install and readiness timeout (default 10m0s)
      --upgrade                     authorize upgrading an existing qhx-core release
      --values stringArray          read supported Helm values from a local YAML file (repeatable)
  -V, --version string              QHx release version or latest


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)

qhx license

Section titled “qhx license”
$ qhx license --help
Inspect and manage QHx licenses


Usage:
  qhx license [command]


Available Commands:
  info        Print information about a signed license file
  install     Install a signed license into Kubernetes
  status      Print cluster license status


Flags:
  -h, --help   help for license


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)


Use "qhx license [command] --help" for more information about a command.

qhx license info

Section titled “qhx license info”
$ qhx license info --help
Print information about a signed license file


Usage:
  qhx license info FILE [flags]


Flags:
  -h, --help   help for info


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)

qhx license install

Section titled “qhx license install”
$ qhx license install --help
Install a signed license into Kubernetes


Usage:
  qhx license install FILE [flags]


Flags:
  -n, --dry-run            Print the license Secret as YAML instead of creating it
  -h, --help               help for install
      --namespace string   Namespace to store the license Secret in (default "qhx-system")


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)

qhx license status

Section titled “qhx license status”
$ qhx license status --help
Print cluster license status


Usage:
  qhx license status [flags]


Flags:
  -h, --help   help for status


Global Flags:
      --debug                       Enable verbose development logging
      --log-devel                   Enable development logging (console output, debug level)
      --log-format string           Log output format: text or json (default "text")
      --log-stacktrace              Include stack traces in error logs
      --spiffe-socket-path string   Path to the SPIFFE Workload API socket (default "unix:///spiffe-workload-api/agent.sock")
  -v, --verbose int                 Log verbosity level (higher is more verbose, default shows errors only) (default -2)