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.10 or later
• A QubitHub account — sign up (registration is open; no waitlist). See Account & Email Verification for the post-signup flow.

1. Install

pip install qubithub

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

qubithub --version    # e.g. qubithub 0.2.0
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), pass the global --format flag before the command:

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

5. Clone a circuit

Clone a circuit to your local machine to inspect it, run it, or use it as a starting point. qubithub clone uses git when it’s available — you get the full commit history — and falls back to a flat HTTP file download otherwise:

qubithub clone QubitHub/bell-state
cd bell-state

A circuit repository typically contains:

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

Open the files in your editor to see how the circuit works.

6. Push changes

When you’ve edited a circuit you own — one you created (see the next step) or a fork of someone else’s — publish a new version with:

qubithub circuits push

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

Note

qubithub circuits push resolves the target as <your-username>/<circuit-name>, so it only updates circuits in your own account. To build on someone else’s circuit, qubithub circuits fork it first — that creates a copy under your account which you can then clone, edit, and push.

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
└── .gitignore          # Sensible ignore defaults

Edit the files, then push. A brand-new circuit needs --create on its first push so the server registers it:

cd my-algorithm
qubithub circuits push --create

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 clone <repo>	Clone a circuit (git, with HTTP fallback)
qubithub circuits list	Browse circuits
qubithub circuits info <repo>	Circuit details
qubithub circuits push	Upload local circuit (--create for new)
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 package also exposes a Python client:

from qubithub import QubitHubClient
from qubithub.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.slug} ({c.framework}) — {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