QLAM Shell

QLAM Shell (qsh) is the official command-line interface for interacting with QLAM services. It provides full access to the quantum task lifecycle—authentication, task submission, monitoring, and result retrieval—all from your terminal.

Features

Full quantum task lifecycle - Create, monitor, and manage quantum tasks, plus retrieve results
Multiple authentication flows - OAuth 2.0 (device code, authorization code, M2M), token auth
Interactive REPL - Tab completion, command history, persistent context
Rich output - Formatted tables with colors, JSON for scripting
Shell completion - Bash, Zsh, Fish, PowerShell

CLI Reference Available

See the QLAM Shell CLI Reference for full command documentation generated from source.

Installation

Install QLAM Shell using uv (recommended) or pip:

uvpip

uv pip install qlam-shell

pip install qlam-shell

Note

QLAM Shell includes qlam-core as a dependency. If you only need programmatic access without the CLI, see Third-Party SDKs.

Shell Completion (Optional)

BashZshFish

qsh completion bash >> ~/.bashrc
source ~/.bashrc

mkdir -p ~/.zsh/completions
qsh completion zsh > ~/.zsh/completions/_qsh
# Add to .zshrc: fpath=(~/.zsh/completions $fpath); autoload -Uz compinit && compinit

qsh completion fish > ~/.config/fish/completions/qsh.fish

Configuration

QLAM Shell uses a configuration file at ~/.qsh/config.json to manage connections to QLAM deployments.

Configuration Structure

{
  "current_context": "production",
  "contexts": [
    {
      "name": "production",
      "qpu": "gemini",
      "defaults": {
        "api_base_url": "https://api.quera.com",
        "qpu_mode": "squin-256q"
      },
      "auth_providers": [
        {
          "name": "oauth",
          "provider": "oauth",
          "client_id": "your-client-id",
          "grant_type": "device_code",
          "scope": "openid profile offline_access",
          "issuer": "https://auth.quera.com"
        }
      ],
      "plugins": {
        "tasks": { "auth_provider": "oauth" },
        "results": { "auth_provider": "oauth" }
      }
    }
  ]
}

Configuration Fields

Field	Description
`current_context`	Active context name
`contexts`	List of named configurations for different QLAM deployments

Context Fields

Field	Description
`name`	Unique identifier for this context
`qpu`	QPU identifier
`defaults.api_base_url`	QLAM API endpoint URL
`defaults.qpu_mode`	Default QPU mode for task submission
`auth_providers`	List of authentication provider configurations
`plugins`	Per-plugin configuration (auth provider, API overrides)

Getting Configuration Values

QuEra will provide the specific values for api_base_url, client_id, issuer, and other deployment-specific settings.

Quick Start

# 1. Login (authenticates with configured providers)
qsh auth login

# 2. List your quantum tasks
qsh tasks list

# 3. View task results
qsh results get <task-id>

# 4. Get JSON output for scripting
qsh --output json tasks list

Authentication

# Login to all providers in current context
qsh auth login

# Login with a specific provider only
qsh auth login oauth

Refresh Tokens

# Refresh credentials non-interactively
qsh auth refresh

# Force refresh even if credentials appear valid
qsh auth refresh --force

Check Status

# List configured providers
qsh auth list

# Show credentials for a provider
qsh auth show oauth

M2M (Client Credentials)

For automated systems that authenticate without user interaction, configure a client_credentials auth provider in your context:

{
  "current_context": "automation",
  "contexts": [
    {
      "name": "automation",
      "qpu": "gemini",
      "defaults": {
        "api_base_url": "https://api.quera.com",
        "qpu_mode": "squin-256q"
      },
      "auth_providers": [
        {
          "name": "m2m",
          "provider": "oauth",
          "client_id": "your-m2m-client-id",
          "client_secret": "your-m2m-client-secret",
          "grant_type": "client_credentials",
          "audience": "https://v2/your-deployment",
          "issuer": "https://auth.quera.com"
        }
      ],
      "plugins": {
        "tasks": { "auth_provider": "m2m" },
        "results": { "auth_provider": "m2m" }
      }
    }
  ]
}

Then authenticate and use the CLI as normal:

# Authenticate using M2M credentials (non-interactive)
qsh auth login m2m

# Commands now use the M2M token
qsh tasks list
qsh results get <task-id>

Cache Tokens Until Expiration

The identity provider enforces a monthly limit on M2M token requests. QLAM Shell caches tokens in ~/.qsh/credentials/, but if you are scripting around qsh auth login, avoid calling it before every command. Instead, call it once and let subsequent commands reuse the cached token.

Securing the Client Secret

Avoid storing client_secret directly in config.json for production use. Instead, inject it via an environment variable or secret manager and write the config file as part of your CI/CD or job startup script.

Commands

Global Options

Option	Description
`--context CONTEXT`	Use a specific context from config
`-o, --output FORMAT`	Output format: `table` (default) or `json`
`-v, --verbose`	Enable debug logging
`--help`	Show help message

Tasks

# List tasks
qsh tasks list
qsh tasks list --all              # Fetch all pages
qsh tasks list --qpu-mode squin-256q

# Get task details
qsh tasks get <task-id>
qsh --output json tasks get <task-id>

# Create a task
qsh tasks create @task-request.json
qsh tasks create '{"programs": [...], "subtasks": [...]}'

# Cancel a task
qsh tasks cancel <task-id>

Results

# Get results
qsh results get <task-id>
qsh results get <task-id> --wide  # Show all columns

# Paginate results
qsh results get <task-id> --page 0 --size 100

# Get raw JSON for analysis
qsh --output json results get <task-id>

Compilations

# List compilations
qsh compilations list

# Get compilation details
qsh compilations get <compilation-id>

# Create a compilation
qsh compilations create @compilation-request.json

Definitions

# List definitions
qsh definitions list

# Get definition details
qsh definitions get <definition-id>

# Create a definition
qsh definitions create @definition-request.json

Interactive REPL

Start an interactive session with persistent context:

qsh repl

Starting QSH Interactive Shell
Type 'help' for available commands or 'exit' to quit.

qsh> auth list
qsh> tasks list
qsh> results get b2c3d4e5-f6a7-8901-bcde-f23456789012
qsh> exit

Features:

Tab completion for commands
Command history (arrow keys)
Context and output format persist across commands

Output Formats

Table Format (Default)

Human-readable tables with responsive column widths and status-based colors.

JSON Format

Machine-readable output for scripting:

qsh --output json tasks list | jq '.[] | .id'

Environment Variables

Variable	Description
`QSH_CONFIG_DIR`	Override config directory (default: `~/.qsh`)
`QSH_CONFIG`	Override config file path
`QSH_AUTH_TOKEN`	Override auth token for all requests
`QSH_QPU`	Override default QPU

Exit Codes

For scripting and CI/CD integration:

Code	Description
0	Success
2	Invalid command or arguments
11	Network error
40	Missing or invalid auth configuration
41	Authentication failed
42	Validation error
44	Resource not found
49	Conflict error (409)
50	Server error
99	Unknown/unexpected error
130	Interrupted by user (Ctrl+C)

Next Steps

Authentication Guide - Understanding authentication options
Third-Party SDKs - Using the QLAM Core library programmatically
Direct API - Raw API access