CLI / SDK Quickstart

This tutorial walks you through installing the QubitHub CLI, running your first quantum circuit, and publishing changes — all from the terminal.

Time to complete: ~5 minutes

Prerequisites

• Python 3.11 or later
• A QubitHub account (sign up or join the waitlist)

1. Install

pip install qubithub-sdk

This installs both the Python SDK and the qubithub CLI. Verify:

qubithub --help

Tip

You can also use the alias qhub instead of qubithub for all commands.

2. Log in

Interactive login (opens a prompt):

qubithub login

Enter your email and password when prompted.

Non-interactive login (CI/CD, scripts):

# With an API key
qubithub login --api-key qh_abc123...

# With an environment variable
export QUBITHUB_API_KEY=qh_abc123...

Verify you’re authenticated:

qubithub whoami

3. Browse circuits

List available circuits:

qubithub circuits list

Filter by framework:

qubithub circuits list --framework qiskit

Filter by tag:

qubithub circuits list --tag entanglement

View details of a specific circuit:

qubithub circuits info QubitHub/bell-state

4. Run a circuit

Execute a circuit and watch the results:

qubithub execute QubitHub/bell-state --shots 1024 --watch

The --watch flag polls until the run completes and displays a histogram of measurement results.

Output (example):

✓ Resolved QubitHub/bell-state → abc123
Submitted run run_456 on qiskit_aer (1024 shots)

⣿ Polling... completed

Measurement Histogram (1024 shots)
|00⟩ ████████████████████ 512 (50.0%)
|11⟩ ████████████████████ 512 (50.0%)

For JSON output (useful for scripting):

qubithub execute QubitHub/bell-state --shots 1024 --watch --format json

5. Clone and modify

Clone a circuit’s files to your local machine:

qubithub circuits clone QubitHub/bell-state
cd bell-state

This downloads:

• circuit.py — the quantum circuit code
• qubithub.toml — circuit manifest (metadata)
• README.md — documentation
• metadata.json — auto-generated metadata

Open circuit.py in your editor and make changes.

6. Push changes

After editing, push your modified circuit back to QubitHub:

qubithub circuits push

The CLI validates your qubithub.toml, uploads all files, and creates a new version.

7. Create a new circuit from scratch

Scaffold a new circuit project:

qubithub circuits init my-algorithm --framework qiskit

This generates a directory with template files:

my-algorithm/
├── circuit.py          # Your circuit code
├── qubithub.toml       # Manifest (edit this!)
└── README.md           # Documentation

Edit the files, then push:

cd my-algorithm
qubithub circuits push

Command reference

Command	Description
qubithub login	Authenticate (interactive or --api-key)
qubithub logout	Clear stored credentials
qubithub whoami	Show current user
qubithub execute <repo>	Execute a circuit
qubithub circuits list	Browse circuits
qubithub circuits info <repo>	Circuit details
qubithub circuits clone <repo>	Download circuit files
qubithub circuits push	Upload local circuit
qubithub circuits init <name>	Scaffold new circuit
qubithub circuits fork <repo>	Fork a circuit
qubithub circuits metadata	Show parsed manifest (-f json|toml)
qubithub runs list	List your runs
qubithub runs info <id>	Run details and results
qubithub runs cancel <id>	Cancel a running execution
qubithub runs stats	Show run statistics
qubithub keys create	Create an API key
qubithub keys list	List API keys
qubithub keys revoke <id>	Revoke an API key
qubithub config set <key> <val>	Set a CLI default
qubithub config get <key>	Get a CLI default
qubithub config list	List all CLI defaults
qubithub config unset <key>	Remove a CLI default

Using the Python SDK

The qubithub-sdk package also exposes a Python client:

from qubithub_sdk import QubitHubClient
from qubithub_sdk.models import RunCreateRequest

client = QubitHubClient(api_key="qh_abc123...")

# List circuits
circuits = client.list_circuits(framework="qiskit")
for c in circuits.circuits:
    print(f"{c.repo_name} — {c.title}")

# Execute a circuit
run = client.create_run(RunCreateRequest(
    circuit_id="<circuit-uuid>",
    backend_name="qiskit_aer",
    shots=1024,
))

Next steps

• Web UI Getting Started — explore QubitHub in the browser
• qubithub.toml Reference — manifest format for publishing
• Authentication — API keys, tokens, and rate limits
• Contributing Circuits — quality standards and best practices