Skip to main content

CLI Installation

The QCOS Command Line Interface provides powerful tools for executing quantum circuits, managing jobs, and automating workflows.

Installation​

Using pip​

pip install qcos-cli
# Install pipx if needed
pip install pipx
pipx ensurepath

# Install QCOS CLI
pipx install qcos-cli

Verify Installation​

qcos --version
# QCOS CLI v1.0.0

Initial Setup​

Configure API Key​

# Interactive setup
qcos configure

# Enter your API key:
# > qcos-xxxx-xxxx-xxxx
# ✓ Configuration saved to ~/.qcos/config.json

Using Environment Variable​

export QCOS_API_KEY="qcos-xxxx-xxxx-xxxx"

Test Connection​

qcos health

# Output:
# ✓ API Gateway: healthy (v1.0.0)
# ✓ Queue Service: connected
# ✓ GPU Workers: 8 available
# ✓ Your tier: pro (73/100 jobs today)

Quick Start​

Execute a Circuit​

# From file
qcos execute circuit.qasm --shots 1024

# Inline (using heredoc)
qcos execute - --shots 1024 << 'EOF'
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;
EOF

View Results​

# Immediate output
qcos execute circuit.qasm --shots 1024

# ✓ Job submitted: job_abc123
# ⏳ Waiting for result...
# ✓ Completed in 1.2s
#
# Results:
# ┌─────────┬───────┬─────────┐
# │ State   │ Count │ Percent │
# ├─────────┼───────┼─────────┤
# │ 00      │ 512   │ 50.0%   │
# │ 11      │ 512   │ 50.0%   │
# └─────────┴───────┴─────────┘

Async Execution​

# Submit without waiting
qcos execute circuit.qasm --no-wait
# ✓ Job submitted: job_abc123

# Check status
qcos status job_abc123
# Status: processing
# Progress: 45%

# Get results
qcos results job_abc123 --format json

Output Formats​

# Table (default)
qcos execute circuit.qasm --format table

# JSON
qcos execute circuit.qasm --format json

# CSV
qcos execute circuit.qasm --format csv

# Save to file
qcos execute circuit.qasm --output results.json

Shell Completion​

Bash​

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

Zsh​

qcos completion zsh >> ~/.zshrc
source ~/.zshrc

Fish​

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

Configuration File​

Location: ~/.qcos/config.json

{
  "api_key": "qcos-xxxx-xxxx-xxxx",
  "api_url": "https://api.softquantus.com",
  "default_shots": 1024,
  "timeout": 60,
  "output_format": "table",
  "color": true
}

Next Steps​