CLI Commands
Complete reference for all QCOS CLI commands.
Core Commands
qcos execute
Execute a quantum circuit.
qcos execute <circuit_file> [options]
Arguments:
circuit_file- Path to QASM file, or-for stdin
Options:
| Option | Short | Default | Description |
|---|---|---|---|
--shots | -s | 1024 | Number of measurement shots |
--wait | -w | true | Wait for completion |
--no-wait | false | Submit and return immediately | |
--timeout | -t | 60 | Max seconds to wait |
--format | -f | table | Output format: table, json, csv |
--output | -o | Save result to file | |
--quiet | -q | false | Suppress progress output |
Examples:
# Basic execution
qcos execute bell.qasm --shots 2048
# Save JSON result
qcos execute bell.qasm -s 1024 -f json -o result.json
# Async execution
qcos execute bell.qasm --no-wait
# From stdin
cat circuit.qasm | qcos execute - --shots 512
qcos status
Check job status.
qcos status <job_id> [options]
Options:
| Option | Short | Default | Description |
|---|---|---|---|
--watch | -w | false | Continuously poll status |
--format | -f | table | Output format |
Examples:
# Check status
qcos status job_abc123
# Watch until complete
qcos status job_abc123 --watch
qcos results
Get job results.
qcos results <job_id> [options]
Options:
| Option | Short | Default | Description |
|---|---|---|---|
--wait | -w | false | Wait for completion |
--timeout | -t | 60 | Max wait time |
--format | -f | table | Output format |
--output | -o | Save to file |
Examples:
# Get results
qcos results job_abc123
# Wait and save
qcos results job_abc123 --wait --output results.json
qcos cancel
Cancel a queued job.
qcos cancel <job_id>
Batch Commands
qcos batch
Execute multiple circuits.
qcos batch <directory> [options]
qcos batch --manifest batch.yaml [options]
Options:
| Option | Short | Default | Description |
|---|---|---|---|
--shots | -s | 1024 | Default shots for all |
--parallel | -p | 4 | Concurrent jobs |
--manifest | -m | YAML manifest file | |
--output-dir | -o | ./results | Output directory |
Manifest Example:
# batch.yaml
jobs:
- name: bell-state
circuit: circuits/bell.qasm
shots: 2048
- name: ghz-5
circuit: circuits/ghz_5.qasm
shots: 4096
- name: qft-8
circuit: circuits/qft_8.qasm
shots: 1024
Examples:
# Execute all QASM files in directory
qcos batch ./circuits --shots 1024
# Execute from manifest
qcos batch --manifest batch.yaml --parallel 8
# Output:
# ✓ Batch started: 5 jobs
# [====================] 100% (5/5)
# ✓ All jobs completed
# Results saved to ./results/
Configuration Commands
qcos configure
Configure CLI settings.
qcos configure [options]
Options:
| Option | Description |
|---|---|
--api-key | Set API key |
--api-url | Set API endpoint |
--set KEY=VALUE | Set any config value |
--unset KEY | Remove config value |
--list | Show current config |
Examples:
# Interactive setup
qcos configure
# Set specific values
qcos configure --api-key qcos-xxxx-xxxx
qcos configure --set default_shots=2048
qcos configure --set output_format=json
# View configuration
qcos configure --list
qcos auth
Manage authentication.
qcos auth <subcommand>
Subcommands:
login- Authenticate via browserlogout- Clear credentialsstatus- Show auth statuscreate-key- Create new API keylist-keys- List API keysrevoke-key- Revoke an API key
Examples:
qcos auth login
# Opens browser for OAuth flow
qcos auth status
# ✓ Authenticated as demo@example.com
# Tier: pro
# API Key: qcos-****-****-1234
qcos auth create-key --name "ci-cd"
# ✓ API Key created: qcos-xxxx-yyyy-zzzz
Information Commands
qcos user
View user information.
qcos user [subcommand]
Subcommands:
info- Show account detailsusage- Show usage statisticsjobs- List recent jobs
Examples:
qcos user info
# User: demo@example.com
# Tier: pro
# Daily limit: 100 jobs
# Max qubits: 50
# Max shots: 100,000
qcos user usage
# Today: 23/100 jobs
# This month: 456 jobs
# Total: 1,234 jobs
qcos user jobs --limit 10
# Recent Jobs:
# │ ID │ Status │ Qubits │ Time │
# │ job_abc123 │ completed │ 5 │ 1.2s │
# │ job_def456 │ completed │ 10 │ 2.5s │
qcos health
Check API health.
qcos health [options]
Options:
| Option | Description |
|---|---|
--json | Output as JSON |
--verbose | Show detailed info |
Examples:
qcos health
# ✓ API Gateway: healthy (v1.0.0)
# ✓ Queue Service: connected
# ✓ GPU Workers: 8 available
qcos health --verbose
# ... detailed diagnostics
qcos pricing
View pricing tiers.
qcos pricing
Output:
┌────────────┬──────────┬────────────┬───────────┬─────────┐
│ Tier │ Jobs/Day │ Max Qubits │ Max Shots │ Price │
├────────────┼──────────┼────────────┼──── ───────┼─────────┤
│ Free │ 10 │ 20 │ 10,000 │ $0 │
│ Pro │ 100 │ 50 │ 100,000 │ $49/mo │
│ Enterprise │ Unlimited│ 100 │ 1,000,000 │ Custom │
└────────────┴──────────┴────────────┴───────────┴─────────┘
Utility Commands
qcos validate
Validate a circuit without executing.
qcos validate <circuit_file>
Examples:
qcos validate circuit.qasm
# ✓ Circuit is valid
# Qubits: 5
# Gates: 12
# Depth: 8
qcos validate invalid.qasm
# ✗ Invalid circuit
# Line 5: Unknown gate 'foo'
qcos convert
Convert between circuit formats.
qcos convert <input> <output> [options]
Examples:
# QASM to JSON
qcos convert circuit.qasm circuit.json
# Qiskit to QASM
qcos convert circuit.py circuit.qasm --from qiskit
qcos completion
Generate shell completion scripts.
qcos completion <shell>
Shells: bash, zsh, fish, powershell
Global Options
Available for all commands:
| Option | Short | Description |
|---|---|---|
--api-key | Override API key | |
--api-url | Override API URL | |
--verbose | -v | Verbose output |
--quiet | -q | Suppress output |
--no-color | Disable colors | |
--help | -h | Show help |
--version | -V | Show version |
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Authentication error |
| 4 | Rate limit exceeded |
| 5 | Quota exceeded |
| 6 | Circuit error |
| 7 | Timeout |
| 8 | Network error |