QHx CLI Reference

Overview

The qhx CLI is a compartment-aware wrapper around kubectl that automatically applies MLS labels and enforces compartment boundaries. It provides the same interface as kubectl while adding security context awareness.

Key features:

Automatic MLS label application
Compartment context switching
Cross-compartment access prevention
Enhanced output with compartment information
Compatible with kubectl commands

Target audience: Developers, operators, and security teams working with MLS-classified workloads.

Installation

Download Binary

# Linux (amd64)
curl -LO https://github.com/messier42/qhx-cli/releases/latest/download/qhx-linux-amd64
chmod +x qhx-linux-amd64
sudo mv qhx-linux-amd64 /usr/local/bin/qhx

# macOS (amd64)
curl -LO https://github.com/messier42/qhx-cli/releases/latest/download/qhx-darwin-amd64
chmod +x qhx-darwin-amd64
sudo mv qhx-darwin-amd64 /usr/local/bin/qhx

# macOS (arm64)
curl -LO https://github.com/messier42/qhx-cli/releases/latest/download/qhx-darwin-arm64
chmod +x qhx-darwin-arm64
sudo mv qhx-darwin-arm64 /usr/local/bin/qhx

# Verify installation
qhx version

From Source

# Requires Go 1.21+
git clone https://github.com/messier42/qhx-cli.git
cd qhx-cli
make install

Shell Completion

# Bash
qhx completion bash | sudo tee /etc/bash_completion.d/qhx

# Zsh
qhx completion zsh | sudo tee /usr/share/zsh/site-functions/_qhx

# Fish
qhx completion fish | sudo tee ~/.config/fish/completions/qhx.fish

Configuration

Configuration File

The CLI reads configuration from ~/.qhx/config.yaml:

currentContext: us-ts-gestalt

contexts:
  us-ts-gestalt:
    country: US
    sensitivity: TS
    compartment: GESTALT
    kubeContext: production-cluster
    namespace: default

  uk-s-marble:
    country: UK
    sensitivity: S
    compartment: MARBLE
    kubeContext: production-cluster
    namespace: default

  au-c-baseline:
    country: AU
    sensitivity: C
    compartment: BASELINE
    kubeContext: staging-cluster
    namespace: default

# Default user groups (applied to all contexts)
defaultUserGroups:
  - system:authenticated

# Kubeconfig path (optional, defaults to ~/.kube/config)
kubeconfig: ~/.kube/config

Environment Variables

# Set compartment via environment
export QHX_COUNTRY=US
export QHX_SENSITIVITY=TS
export QHX_COMPARTMENT=GESTALT

# Override kubeconfig
export KUBECONFIG=~/.kube/production-config

# Debug mode
export QHX_DEBUG=true

Precedence: Environment variables override configuration file values.

Core Commands

qhx curl

Make HTTP requests with workload identity validation and request notarization.

Purpose: Test QHx-protected services and verify notarization levels.

Usage:

qhx curl [flags] <url>

Notarization Levels:

The -n or --notarization-level flag selects the notarization level:

workload (default) - Validate workload identity statement only (lowest overhead)
logRequest - Validate workload identity; request is logged by notary
signRequest - Validate workload identity and signed receipt; highest notarization (highest overhead)

Key Features:

Validates QHx workload identity statements
Verifies request notarization receipts
Prints detailed notarization data
Compatible with standard curl flags
Exits with non-zero code if validation fails

Examples:

# Basic request with default (workload) notarization
qhx curl http://api-server:8080/health

# Request with signed receipt
qhx curl -n signRequest http://api-server:8080/api/inference

# POST request with data
qhx curl -X POST -d '{"query":"hello"}' \
  -H "Content-Type: application/json" \
  http://api-server:8080/api/chat

# Print workload identity statement
qhx curl --print-workload http://api-server:8080/

# Print request receipt (requires signRequest)
qhx curl -n signRequest --print-receipt http://api-server:8080/

# Show response headers
qhx curl -i http://api-server:8080/

# Silent mode (no progress)
qhx curl -s http://api-server:8080/health

Workload Identity Statement Output:

qhx curl --print-workload http://ollama-server:8080/

# Output:
Trust Domain:           qhx.dev
SPIFFE ID:              spiffe://qhx.dev/ns/ai-demo/sa/ollama/pod/ollama-abc123/...
Namespace:              ai-demo
Service Account:        ollama
Pod Name:               ollama-server-786f9f59d-5djst
Pod UID:                9d86dd35-31fd-4271-bb10-579bfe434d58

Container Images:
  - ollama/ollama:latest
  - qhx/proxy:v0.6.1

Labels:
  app: ollama-server
  pod-template-hash: 786f9f59d

Annotations:
  mls.qhx.dev/compartment: GESTALT
  mls.qhx.dev/level: TS

Raw Claims (JSON):
{
  "iss": "spiffe://qhx.dev/ns/qhx-central/sa/central-proxy/...",
  "sub": "spiffe://qhx.dev/ns/ai-demo/sa/ollama/...",
  "aud": "https://qhx.dev/workload-statement",
  "iat": 1760673752,
  "qhx": {
    "trustDomain": "qhx.dev",
    "namespace": "ai-demo",
    "podName": "ollama-server-786f9f59d-5djst",
    ...
  }
}

Request Receipt Output:

qhx curl -n signRequest --print-receipt \
  -X POST -d '{"model":"llama3.2:1b","messages":[{"role":"user","content":"Hello"}]}' \
  http://ollama-server:8080/v1/chat/completions

# Output:
Signed Request Receipt "K8MKUqJsgmenKSchf06c5w==":
==================================================
Issuer:                 spiffe://qhx.dev/ns/qhx-central/sa/central-proxy/...
Audience:               [https://qhx.dev/receipt]
Issued At:              2026-02-02T10:48:07Z

Workload Statement ID:  VGkHGqleoIQHBiGlowdMh947YojeuMwTjhtELksaPs8=

HTTP Request:
  Method:               POST
  Path:                 /v1/chat/completions
  Headers:
    Content-Type: application/json
  Body (110 bytes):      {"model":"llama3.2:1b",...}

HTTP Response:
  Status Code:          200
  Headers:
    Content-Type: application/json
  Body (351 bytes):      {"id":"chatcmpl-500",...}

Raw Claims (JSON):
{
  "iss": "spiffe://qhx.dev/ns/qhx-central/sa/central-proxy/...",
  "aud": "https://qhx.dev/receipt",
  "iat": 1760680087,
  "qhx": {
    "workloadStatementID": "VGkHGqleoIQHBiGlowdMh947...",
    "request": {...},
    "response": {...}
  }
}

Flags:

Flag	Description
`-d`, `--data <str>`	Specify HTTP POST data
`-H`, `--header <str>`	Add HTTP header to request
`-n`, `--notarization-level <level>`	Select notarization level (`workload`, `logRequest`, `signRequest`)
`--print-workload`	Print workload identity statement
`--print-receipt`	Print request notarization receipt (requires `signRequest`)
`-X`, `--request <method>`	Select HTTP request method (GET, POST, PUT, DELETE, etc.)
`-i`, `--show-headers`	Show HTTP headers in response
`-s`, `--silent`	Silent mode (no progress output)
`--validate <bool>`	Require workload statement verification (default: true)

Global Flags:

Flag	Description
`--log-level <level>`	Enable development logging (console output, debug level)
`--log-format <format>`	Log output format: `text` or `json` (default: `text`)
`--log-stacktrace`	Include stack traces in error logs
`--spiffe-socket-path <path>`	Path to Workload API socket (default: `unix:///spiffe-workload-api/agent.sock`)
`-v`, `--verbose <int>`	Log verbosity level (higher is more verbose, default: -2)

Use Cases:

1. Testing AI Inference with Audit Trail:

# Call LLM with signed receipt for compliance
qhx curl -n signRequest --print-receipt \
  -X POST -H "Content-Type: application/json" \
  -d '{"model":"llama3.2:1b","messages":[{"role":"user","content":"Classify this document"}]}' \
  http://ollama-server:8080/v1/chat/completions \
  > inference-receipt.json

# Receipt proves:
# - Which model handled the request
# - Exact request/response
# - Timestamp
# - Workload identity

2. Verifying Service Identity:

# Confirm which workload is running
qhx curl --print-workload http://api-server:8080/health | grep "Container Images"

# Output shows exact OCI image digest:
# Container Images:
#   - api-server:v1.0@sha256:abc123...

3. Debugging Network Policies:

# Test if request is allowed
qhx curl http://blocked-service:8080/

# If blocked by policy:
# Error: Connection refused (likely NetworkPolicy denial)

# If blocked by QHx:
# Error: Workload statement verification failed

4. Performance Testing:

# Test overhead of different notarization levels
time qhx curl -n workload http://api:8080/     # ~1ms overhead
time qhx curl -n logRequest http://api:8080/   # ~2ms overhead
time qhx curl -n signRequest http://api:8080/  # ~5-10ms overhead

Exit Codes:

0 - Success (request completed and notarization validated)
1 - Network error (connection failed)
2 - Workload statement validation failed
3 - Request receipt validation failed
4 - HTTP error (4xx or 5xx response)

Validation Behavior:

By default, qhx curl requires workload statement validation (--validate=true). If the server does not return valid notarization headers, the command fails:

# Calling non-QHx service fails validation
qhx curl http://external-api.com/
# Error: workload statement verification required but Qhx-Workload-ID header not present

# Disable validation for non-QHx services
qhx curl --validate=false http://external-api.com/
# ✅ Success (no validation)

Comparison with standard curl:

Feature	`curl`	`qhx curl`
HTTP requests	✅	✅
TLS/mTLS	✅	✅ (automatic via SPIFFE)
Workload identity	❌	✅
Request notarization	❌	✅
Offline verification	❌	✅ (with signed receipts)

qhx identity

Display current compartment context.

Usage:

qhx identity

Example output:

Compartment:     US-TS-GESTALT
Country:         US
Sensitivity:     TS
Compartment:     GESTALT
Kube Context:    production-cluster
User:            alice@example.com
User Groups:     system:authenticated, qhx:country:us, qhx:sensitivity:ts, qhx:compartment:gestalt

Use case: Verify compartment before deploying classified workloads.

qhx apply

Apply Kubernetes resources with automatic MLS label injection.

Usage:

qhx apply -f FILENAME [flags]

Behavior:

Reads current compartment context
Injects mls.qhx.dev/level and mls.qhx.dev/compartment labels
Applies resources via Kubernetes API
Returns standard kubectl output

Examples:

# Apply deployment in current compartment
qhx apply -f deployment.yaml

# Apply with namespace override
qhx apply -f app.yaml -n my-namespace

# Apply from URL
qhx apply -f https://example.com/manifest.yaml

# Apply directory
qhx apply -f ./manifests/

# Dry-run to see what would be applied
qhx apply -f deployment.yaml --dry-run=client -o yaml

Label injection example:

Input YAML:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
      - name: api
        image: api:v1.0

After qhx apply (with context US-TS-GESTALT):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  namespace: production
  labels:
    qhx.io/compartment: US-TS-GESTALT  # Injected
  annotations:
    mls.qhx.dev/level: us:ts            # Injected
    mls.qhx.dev/compartment: us:gestalt # Injected
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
        qhx.io/compartment: US-TS-GESTALT  # Injected
      annotations:
        mls.qhx.dev/level: us:ts            # Injected
        mls.qhx.dev/compartment: us:gestalt # Injected
    spec:
      containers:
      - name: api
        image: api:v1.0

qhx get

Retrieve resources with compartment information.

Usage:

qhx get RESOURCE [NAME] [flags]

Enhanced output: Adds COMPARTMENT column to standard kubectl output.

Examples:

# List all pods with compartment
qhx get pod

# Output:
# NAME                   READY   STATUS    RESTARTS   COMPARTMENT
# us-api-7f8c9d-xyz      1/1     Running   0          US-TS-GESTALT
# uk-web-5b6d8a-abc      1/1     Running   0          UK-S-MARBLE
# au-db-9c4e2b-def       1/1     Running   0          AU-C-BASELINE

# Get specific pod details
qhx get pod us-api-7f8c9d-xyz -o yaml

# List deployments across all namespaces
qhx get deployment -A

# Watch pods in real-time
qhx get pod -w

# Filter by label
qhx get pod -l app=api

# Custom columns
qhx get pod -o custom-columns=NAME:.metadata.name,COMPARTMENT:.metadata.labels.qhx\\.io/compartment

Compartment filtering:

# Show only resources in current compartment
qhx get pod --filter-compartment

# Show resources in specific compartment
qhx get pod --compartment=UK-S-MARBLE

qhx exec

Execute commands in pods with compartment boundary enforcement.

Usage:

qhx exec POD_NAME [-c CONTAINER] -- COMMAND [args...]

Security: Prevents execution in pods outside current compartment.

Examples:

# Execute command in pod (same compartment)
qhx exec us-api-7f8c9d-xyz -- curl http://localhost:8080/health
# ✅ Success (same compartment)

# Attempt to execute in different compartment
qhx exec uk-web-5b6d8a-abc -- curl http://localhost:8080/health
# ❌ Error: Cannot execute in pod in another compartment (UK-S-MARBLE)
#    Current compartment: US-TS-GESTALT

# Specify container
qhx exec us-api-7f8c9d-xyz -c sidecar -- ps aux

# Interactive shell
qhx exec -it us-api-7f8c9d-xyz -- /bin/bash

# Execute with stdin
echo "SELECT * FROM users;" | qhx exec us-db-pod -- psql -U admin

Override (admin only):

# Force execution in different compartment (requires special permission)
qhx exec uk-web-5b6d8a-abc --force -- curl http://localhost:8080/health

qhx logs

Retrieve logs from pods.

Usage:

qhx logs POD_NAME [-c CONTAINER] [flags]

Examples:

# Get logs from pod
qhx logs us-api-7f8c9d-xyz

# Follow logs
qhx logs -f us-api-7f8c9d-xyz

# Logs from specific container
qhx logs us-api-7f8c9d-xyz -c qhx-proxy

# Previous logs (from crashed container)
qhx logs us-api-7f8c9d-xyz --previous

# Last 100 lines
qhx logs us-api-7f8c9d-xyz --tail=100

# Logs since timestamp
qhx logs us-api-7f8c9d-xyz --since=1h

qhx delete

Delete resources (with compartment awareness).

Usage:

qhx delete RESOURCE NAME [flags]

Safety: Warns when deleting resources in different compartment.

Examples:

# Delete deployment
qhx delete deployment us-api

# Delete multiple resources
qhx delete pod us-api-xyz us-api-abc

# Delete by label
qhx delete pod -l app=old-version

# Delete from file
qhx delete -f deployment.yaml

# Force delete (skip warnings)
qhx delete deployment us-api --force

qhx describe

Show detailed information about resources.

Usage:

qhx describe RESOURCE NAME

Enhanced output: Highlights MLS labels and compartment information.

Example:

qhx describe pod us-api-7f8c9d-xyz

# Output includes:
# Name:         us-api-7f8c9d-xyz
# Namespace:    production
# Labels:       app=api
#               qhx.io/compartment=US-TS-GESTALT
# Annotations:  mls.qhx.dev/level: us:ts
#               mls.qhx.dev/compartment: us:gestalt
# ...

qhx port-forward

Forward ports from pods or services.

Usage:

qhx port-forward POD_NAME [LOCAL_PORT:]REMOTE_PORT [flags]

Examples:

# Forward port 8080 to localhost:8080
qhx port-forward us-api-7f8c9d-xyz 8080:8080

# Forward to different local port
qhx port-forward us-api-7f8c9d-xyz 9090:8080

# Forward multiple ports
qhx port-forward us-api-7f8c9d-xyz 8080:8080 9090:9090

# Forward from service
qhx port-forward service/us-api 8080:80

qhx cp

Copy files to/from containers.

Usage:

qhx cp SOURCE DEST [flags]

Examples:

# Copy from pod to local
qhx cp us-api-7f8c9d-xyz:/var/log/app.log ./app.log

# Copy from local to pod
qhx cp ./config.yaml us-api-7f8c9d-xyz:/etc/app/config.yaml

# Copy from specific container
qhx cp us-api-7f8c9d-xyz:/logs/error.log ./error.log -c sidecar

Context Management

qhx context

Manage compartment contexts.

Usage:

qhx context [SUBCOMMAND]

Subcommands:

list

List available contexts:

qhx context list

# Output:
# CURRENT   NAME             COUNTRY   SENSITIVITY   COMPARTMENT   KUBE-CONTEXT
# *         us-ts-gestalt    US        TS            GESTALT       prod-cluster
#           uk-s-marble      UK        S             MARBLE        prod-cluster
#           au-c-baseline    AU        C             BASELINE      staging-cluster

use

Switch to a different context:

# Switch context
qhx context use uk-s-marble

# Verify switch
qhx identity
# Output:
# Compartment:     UK-S-MARBLE
# ...

create

Create a new context:

qhx context create jp-s-quantum \
  --country=JP \
  --sensitivity=S \
  --compartment=QUANTUM \
  --kube-context=production-cluster

delete

Remove a context:

qhx context delete au-c-baseline

current

Show current context:

qhx context current
# Output: us-ts-gestalt

Advanced Features

Compartment Filtering

Filter resources by compartment:

# Show only pods in current compartment
qhx get pod --current-compartment

# Show pods in specific compartment
qhx get pod --compartment US-TS-GESTALT

# Show pods NOT in current compartment
qhx get pod --exclude-current-compartment

Dry Run Mode

Preview changes without applying:

# See what labels would be injected
qhx apply -f deployment.yaml --dry-run=client -o yaml

# Server-side dry run
qhx apply -f deployment.yaml --dry-run=server

JSON/YAML Output

# Get pod as JSON
qhx get pod us-api-xyz -o json

# Get deployment as YAML
qhx get deployment us-api -o yaml

# Custom JSON path
qhx get pod us-api-xyz -o jsonpath='{.metadata.labels.qhx\.io/compartment}'

Watching Resources

# Watch pods
qhx get pod -w

# Watch events
qhx get events -w

# Watch with timestamps
qhx get pod -w --show-labels=true

Integration with kubectl

Compatibility

The qhx CLI is fully compatible with kubectl. Any kubectl command works with qhx:

# These are equivalent (with compartment context added):
kubectl get pod
qhx get pod

kubectl apply -f deployment.yaml
qhx apply -f deployment.yaml

Aliases

Add to your shell configuration (~/.bashrc or ~/.zshrc):

# Use qhx by default
alias kubectl='qhx'

# Quick compartment switching
alias qhx-us='qhx context use us-ts-gestalt'
alias qhx-uk='qhx context use uk-s-marble'
alias qhx-au='qhx context use au-c-baseline'

Compartment Scripts

Shell Integration

Create compartment setup scripts:

export QHX_COUNTRY=US
export QHX_SENSITIVITY=TS
export QHX_COMPARTMENT=GESTALT
PS1='(US-TS)$ '

# Source the script
source ./us_compartment.sh

Multi-Compartment Workflow

Use case: Deploy the same application to multiple compartments

#!/bin/bash
for compartment in us-ts-gestalt uk-s-marble au-c-baseline; do
  echo "Deploying to $compartment..."
  qhx context use $compartment
  qhx apply -f deployment.yaml
  qhx rollout status deployment/api-server
done

echo "Deployment complete across all compartments"

Configuration Examples

Development Setup

# ~/.qhx/config.yaml (development)
currentContext: dev-unclassified

contexts:
  dev-unclassified:
    country: US
    sensitivity: U
    compartment: DEV
    kubeContext: minikube
    namespace: default

defaultUserGroups:
  - system:authenticated
  - qhx:country:us
  - qhx:sensitivity:u

Production Setup

# ~/.qhx/config.yaml (production)
currentContext: us-ts-gestalt

contexts:
  us-ts-gestalt:
    country: US
    sensitivity: TS
    compartment: GESTALT
    kubeContext: prod-us-west-1
    namespace: classified-apps

  us-s-default:
    country: US
    sensitivity: S
    compartment: DEFAULT
    kubeContext: prod-us-west-1
    namespace: secret-apps

# Require explicit context switching
requireExplicitContextSwitch: true

# Audit log
auditLog:
  enabled: true
  path: ~/.qhx/audit.log

Troubleshooting

Issue: “Cannot execute in pod in another compartment”

Cause: Attempting to execute commands in a pod outside current compartment.

Solution:

# Check current compartment
qhx identity

# Switch to correct compartment
qhx context use <correct-compartment>

# Or use --force (admin only)
qhx exec <pod> --force -- <command>

Issue: Labels not being applied

Cause: Configuration not set or environment variables missing.

Check:

# Verify configuration
cat ~/.qhx/config.yaml

# Verify environment
env | grep QHX

# Test with dry-run
qhx apply -f test.yaml --dry-run=client -o yaml | grep mls.qhx.dev

Issue: “Context not found”

Cause: Referenced context doesn’t exist in config.

Solution:

# List available contexts
qhx context list

# Create missing context
qhx context create <context-name> --country=... --sensitivity=... --compartment=...

Best Practices

1. Always Verify Context

# Before any operation
qhx identity

2. Use Dry-Run for Testing

# Preview changes
qhx apply -f deployment.yaml --dry-run=client -o yaml | less

3. Label Resources Explicitly

# Include compartment in resource names
metadata:
  name: us-api-server  # Prefix with compartment

4. Audit Logging

Enable audit logging in production:

auditLog:
  enabled: true
  path: ~/.qhx/audit.log
  level: info  # debug, info, warn, error

5. Compartment Naming Convention

<country>-<sensitivity>-<compartment>

Examples:
- us-ts-gestalt
- uk-s-marble
- au-c-baseline
- jp-u-public

Compartment Management Guide - Setting up compartments
MLS Policy Authoring - Policy configuration
Attestation Strategies - Workload identity
Quick Start Guide - Getting started

Command Reference

Command	Description	Example
`qhx curl`	HTTP requests with notarization	`qhx curl -n signRequest <url>`
`qhx identity`	Show current compartment	`qhx identity`
`qhx apply`	Apply with labels	`qhx apply -f app.yaml`
`qhx get`	Get resources	`qhx get pod`
`qhx exec`	Execute in pod	`qhx exec pod -- cmd`
`qhx logs`	Get logs	`qhx logs pod`
`qhx delete`	Delete resources	`qhx delete pod name`
`qhx describe`	Describe resource	`qhx describe pod name`
`qhx port-forward`	Forward ports	`qhx port-forward pod 8080`
`qhx cp`	Copy files	`qhx cp pod:/path ./`
`qhx context`	Manage contexts	`qhx context list`

Support

Documentation: https://docs.messier42.com
GitHub: https://github.com/messier42/qhx-cli
Issues: https://github.com/messier42/qhx-cli/issues

QHx CLI Reference

Overview

Installation

Download Binary

From Source

Shell Completion

Configuration

Configuration File

Environment Variables

Core Commands

qhx curl

qhx identity

qhx apply

qhx get

qhx exec

qhx logs

qhx delete

qhx describe

qhx port-forward

qhx cp

Context Management

qhx context

list

use

create

delete

current

Advanced Features

Compartment Filtering

Dry Run Mode

JSON/YAML Output

Watching Resources

Integration with kubectl

Compatibility

Aliases

Compartment Scripts

Shell Integration

Multi-Compartment Workflow

Configuration Examples

Development Setup

Production Setup

Troubleshooting

Issue: “Cannot execute in pod in another compartment”

Issue: Labels not being applied

Issue: “Context not found”

Best Practices

1. Always Verify Context

2. Use Dry-Run for Testing

3. Label Resources Explicitly

4. Audit Logging

5. Compartment Naming Convention

Related Documentation

Command Reference

Support