$ quantum-cli

Powerful command-line interface for quantum computing. Execute circuits, manage jobs, monitor backends, and automate workflows from your terminal. Cross-platform support for Linux, macOS, and Windows. Full scripting and CI/CD integration capabilities.

Install Now View Docs

Installation

Install via Package Manager

Choose your platform:

# Linux / macOS (Homebrew)
$ brew install ishara-quantum/tap/quantum-cli

# Linux (apt)
$ sudo apt install quantum-cli

# macOS / Linux (curl)
$ curl -fsSL https://cli.agiquantumcloud.com/install.sh | bash

# Windows (PowerShell)
> iwr https://cli.agiquantumcloud.com/install.ps1 | iex

# Python (pip)
$ pip install quantum-cli

Configuration

Set up authentication with your API key:

$ quantum-cli auth login
Enter your API key: ********************************
✓ Authentication successful
✓ Default backend set to: quantum_simulator

$ quantum-cli config set backend superconducting_qpu
✓ Default backend updated

Verify Installation

$ quantum-cli --version
quantum-cli version 3.2.1

$ quantum-cli backends list
Available backends:
  ✓ quantum_simulator     (online)  - 64 qubits
  ✓ superconducting_qpu   (online)  - 127 qubits
  ✓ trapped_ion_qpu       (online)  - 32 qubits

Core Commands

quantum-cli run

Execute a quantum circuit from a file or inline definition

quantum-cli run [circuit-file] [options]

Options:

Option Description Default
--backend, -b Backend name to execute on quantum_simulator
--shots, -s Number of execution shots 1024
--optimize Enable circuit optimization true
--output, -o Output format (json|csv|plot) json

Example:

$ quantum-cli run bell_state.qasm --backend superconducting_qpu --shots 2048
✓ Circuit compiled successfully
✓ Job submitted: qjob_xyz789
⟳ Waiting for execution...
✓ Job completed in 12.3s

Results:
  |00⟩: 1029 (50.2%)
  |11⟩: 1019 (49.8%)
quantum-cli jobs

Manage and monitor quantum computing jobs

quantum-cli jobs [list|get|cancel|wait] [options]

Subcommands:

$ quantum-cli jobs list
Recent jobs:
  qjob_abc123  completed  2m ago   superconducting_qpu
  qjob_def456  running    now      quantum_simulator
  qjob_ghi789  queued     -        trapped_ion_qpu

$ quantum-cli jobs get qjob_abc123
Job ID: qjob_abc123
Status: completed
Backend: superconducting_qpu
Created: 2024-01-15 10:30:00
Completed: 2024-01-15 10:30:15
Duration: 15.2s

$ quantum-cli jobs wait qjob_def456
⟳ Waiting for job qjob_def456...
✓ Job completed
quantum-cli backends

List and inspect available quantum backends

quantum-cli backends [list|info] [backend-name]

Example:

$ quantum-cli backends info superconducting_qpu
Backend: superconducting_qpu
Status: online
Type: hardware
Qubits: 127
Connectivity: Heavy-hex lattice
Gate fidelity: 99.95%
T1 coherence: 150 μs
T2 coherence: 200 μs
Queue length: 3 jobs
Avg wait time: 45 seconds
quantum-cli circuit

Create, validate, and visualize quantum circuits

quantum-cli circuit [create|validate|draw|transpile] [options]

Example:

$ quantum-cli circuit create --qubits 2 --output bell.qasm
✓ Circuit created: bell.qasm

$ quantum-cli circuit validate bell.qasm
✓ Circuit is valid
  Qubits: 2
  Gates: 2
  Depth: 2

$ quantum-cli circuit draw bell.qasm
        ┌───┐     
q_0: ───┤ H ├──■──
        └───┘┌─┴─┐
q_1: ────────┤ X ├
             └───┘

Usage Examples

Execute Bell State Circuit

Create and execute a simple Bell state (entangled qubits):

$ cat > bell.qasm << 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

$ quantum-cli run bell.qasm --shots 1000
✓ Results: |00⟩: 503, |11⟩: 497

VQE Algorithm Execution

Run Variational Quantum Eigensolver for molecular simulation:

$ quantum-cli run vqe_h2.py \
    --backend superconducting_qpu \
    --optimizer COBYLA \
    --maxiter 100
⟳ Running VQE optimization...
Iteration 50: Energy = -1.135 Ha
Iteration 100: Energy = -1.137 Ha
✓ Ground state energy: -1.1373 Ha
✓ Convergence achieved in 87 iterations

Batch Job Submission

Submit multiple circuits from a directory:

$ quantum-cli batch submit circuits/*.qasm \
    --backend quantum_simulator \
    --shots 2048
✓ Submitted 15 jobs
  qjob_001 - qjob_015
⟳ Monitoring completion...
✓ All jobs completed (avg time: 8.2s)

Scripting & Automation

Integrate quantum computing into CI/CD pipelines, shell scripts, and automation workflows.

Shell Script

Automate quantum workflows with bash:

#!/bin/bash
for circuit in *.qasm; do
  quantum-cli run "$circuit" \
    --shots 1024 \
    --output results/"$circuit".json
done

CI/CD Pipeline

GitHub Actions integration:

- name: Test Quantum
  run: |
    quantum-cli run test.qasm
    quantum-cli validate \
      --results results.json

Python Integration

Call CLI from Python scripts:

import subprocess

result = subprocess.run([
    'quantum-cli', 'run',
    'circuit.qasm',
    '--output', 'json'
], capture_output=True)

Features

Cross-Platform

Works on Linux, macOS, and Windows. Consistent interface across all platforms. Native binary executables for performance.

Auto-Complete

Shell completion for bash, zsh, and fish. Tab completion for commands, options, and file paths. Install with quantum-cli completion.

Output Formats

Multiple output formats: JSON, CSV, YAML, plain text. Formatted tables with colors. Export-ready data for analysis.

Interactive Mode

REPL-style interactive shell. Real-time backend monitoring. Live job status updates. Syntax highlighting.

Configuration

Save default settings and preferences. Per-project configuration files. Environment variable support. Profile management.

Error Handling

Detailed error messages with suggestions. Circuit validation before submission. Automatic retry on transient errors. Debug mode available.

$ install quantum-cli

Get started with the most powerful quantum computing CLI. Free and open source. Works with all major quantum cloud providers. Comprehensive documentation included.

Install Now View on GitHub