CLI Commands
Complete reference for all QCOS CLI commands.
Core Commands
softqcos execute
Execute a quantum circuit.
softqcos 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
softqcos execute bell.qasm --shots 2048
# Save JSON result
softqcos execute bell.qasm -s 1024 -f json -o result.json
# Async execution
softqcos execute bell.qasm --no-wait
# From stdin
cat circuit.qasm | softqcos execute - --shots 512
softqcos status
Check job status.
softqcos status <job_id> [options]
Options:
| Option | Short | Default | Description |
|---|---|---|---|
--watch | -w | false | Continuously poll status |
--format | -f | table | Output format |
Examples:
# Check status
softqcos status job_abc123
# Watch until complete
softqcos status job_abc123 --watch
softqcos results
Get job results.
softqcos 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
softqcos results job_abc123
# Wait and save
softqcos results job_abc123 --wait --output results.json
softqcos cancel
Cancel a queued job.
softqcos cancel <job_id>
Batch Commands
softqcos batch
Execute multiple circuits.
softqcos batch <directory> [options]
softqcos 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
softqcos batch ./circuits --shots 1024
# Execute from manifest
softqcos batch --manifest batch.yaml --parallel 8
# Output:
# ✓ Batch started: 5 jobs
# [====================] 100% (5/5)
# ✓ All jobs completed
# Results saved to ./results/
Configuration Commands
softqcos configure
Configure CLI settings.
softqcos 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
softqcos configure
# Set specific values
softqcos configure --api-key softqcos-xxxx-xxxx
softqcos configure --set default_shots=2048
softqcos configure --set output_format=json
# View configuration
softqcos configure --list
softqcos auth
Manage authentication.
softqcos 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:
softqcos auth login
# Opens browser for OAuth flow
softqcos auth status
# ✓ Authenticated as demo@example.com
# Tier: pro
# API Key: softqcos-****-****-1234
softqcos auth create-key --name "ci-cd"
# ✓ API Key created: softqcos-xxxx-yyyy-zzzz
Information Commands
softqcos user
View user information.
softqcos user [subcommand]
Subcommands:
info- Show account detailsusage- Show usage statisticsjobs- List recent jobs
Examples:
softqcos user info
# User: demo@example.com
# Tier: pro
# Daily limit: 100 jobs
# Max qubits: 50
# Max shots: 100,000
softqcos user usage
# Today: 23/100 jobs
# This month: 456 jobs
# Total: 1,234 jobs
softqcos user jobs --limit 10
# Recent Jobs:
# │ ID │ Status │ Qubits │ Time │
# │ job_abc123 │ completed │ 5 │ 1.2s │
# │ job_def456 │ completed │ 10 │ 2.5s │
softqcos health
Check API health.
softqcos health [options]
Options:
| Option | Description |
|---|---|
--json | Output as JSON |
--verbose | Show detailed info |
Examples:
softqcos health
# ✓ API Gateway: healthy (v1.0.0)
# ✓ Queue Service: connected
# ✓ GPU Workers: 8 available
softqcos health --verbose
# ... detailed diagnostics
softqcos pricing
View pricing tiers.
softqcos 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
softqcos validate
Validate a circuit without executing.
softqcos validate <circuit_file>
Examples:
softqcos validate circuit.qasm
# ✓ Circuit is valid
# Qubits: 5
# Gates: 12
# Depth: 8
softqcos validate invalid.qasm
# ✗ Invalid circuit
# Line 5: Unknown gate 'foo'
softqcos convert
Convert between circuit formats.
softqcos convert <input> <output> [options]
Examples:
# QASM to JSON
softqcos convert circuit.qasm circuit.json
# Qiskit to QASM
softqcos convert circuit.py circuit.qasm --from qiskit
softqcos completion
Generate shell completion scripts.
softqcos 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 |