CLI 完整 walkthrough¶

下面这个例子通过 subprocess 把所有最常用的 CLI 子命令连续跑了一遍，输出就是 CLI 真实的样子。本页内容由 examples/4_cli/01_cli_walkthrough.py 自动生成，保证只要本地能 make html，示例就可运行。

01 — CLI walkthrough: all the `uniqc` subcommands¶

Source: examples/4_cli/01_cli_walkthrough.py
Status: pass

把所有常用 CLI 子命令通过 subprocess.run 拉一遍，方便你看到每个命令的实际输出形态。覆盖：

uniqc --help
uniqc backend list
uniqc simulate <file>
uniqc submit <file> --backend dummy --wait
uniqc result <task_id>
uniqc task list

需要真实 token 的子命令（uniqc config set originq.token ...、uniqc submit --backend originq:...、 uniqc calibrate xeb）只演示帮助文本，不会真的提交。

Source code

"""01 — CLI walkthrough: all the ``uniqc`` subcommands

[doc-require: ]
[doc-output-include: stdout, source]

把所有常用 CLI 子命令通过 ``subprocess.run`` 拉一遍，方便你看到每个命令的实际输出
形态。覆盖：

* ``uniqc --help``
* ``uniqc backend list``
* ``uniqc simulate <file>``
* ``uniqc submit <file> --backend dummy --wait``
* ``uniqc result <task_id>``
* ``uniqc task list``

需要真实 token 的子命令（``uniqc config set originq.token ...``、``uniqc submit --backend originq:...``、
``uniqc calibrate xeb``）只演示帮助文本，不会真的提交。
"""

from __future__ import annotations

import json
import pathlib
import subprocess
import sys
import tempfile

PROJECT_ROOT = pathlib.Path(__file__).resolve().parents[2]


def _run(args: list[str]) -> str:
    result = subprocess.run(
        [sys.executable, "-m", "uniqc.cli", *args],
        cwd=PROJECT_ROOT,
        capture_output=True,
        text=True,
        check=False,
    )
    return result.stdout or result.stderr


def main() -> None:
    print("== uniqc --help ==")
    print(_run(["--help"]))

    print("== uniqc backend list (dummy only; cloud backends require credentials) ==")
    print(_run(["backend", "list", "--platform", "dummy"]))

    workdir = pathlib.Path(tempfile.mkdtemp(prefix="uniqc-cli-walk-"))
    bell = workdir / "bell.originir"
    bell.write_text(
        "QINIT 2\nCREG 2\nH q[0]\nCNOT q[0], q[1]\n"
        "MEASURE q[0], c[0]\nMEASURE q[1], c[1]\n",
        encoding="utf-8",
    )

    print("== uniqc simulate bell.originir --shots 256 ==")
    print(_run(["simulate", str(bell), "--shots", "256"]))

    print("== uniqc submit bell.originir --backend dummy -s 64 --wait --format json ==")
    out = _run(["submit", str(bell), "--backend", "dummy", "-s", "64", "--wait", "--format", "json"])
    print(out)

    try:
        payload = json.loads(out)
        task_id = payload.get("task_id") or payload.get("id")
    except Exception:
        task_id = None

    if task_id:
        print(f"== uniqc result {task_id} ==")
        print(_run(["result", task_id]))

    print("== uniqc task list (most recent few) ==")
    print(_run(["task", "list", "--limit", "5"]))


if __name__ == "__main__":
    main()

Stdout

== uniqc --help ==
                                                                                                                        
 Usage: python -m uniqc.cli [OPTIONS] COMMAND [ARGS]...                                                                 
                                                                                                                        
 UnifiedQuantum CLI — A lightweight quantum computing framework GitHub  |  Documentation                                
                                                                                                                        
 Pass --ai-hints/--ai-hint, set UNIQC_AI_HINTS=1, or run uniqc config always-ai-hint on to show AI workflow guidance.   
 AI Agent 安装建议：                                                                                                    
 Codex:  npx skills add IAI-USTC-Quantum/quantum-computing.skill --agent codex --skill '*'                              
 Claude Code: npx skills add IAI-USTC-Quantum/quantum-computing.skill --agent claude-code --skill '*'                   
                                                                                                                        
 默认按仓库安装本仓库全部 skill（推荐）。                                                                               
                                                                                                                        
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --version             -V        Show version and exit                                                                │
│ --install-completion            Install completion for the current shell.                                            │
│ --show-completion               Show completion for the current shell, to copy it or customize the installation.     │
│ --help                          Show this message and exit.                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ circuit    Circuit format conversion (OriginIR <-> QASM)                                                             │
│            CLI Docs  |  GitHub                                                                                       │
│ simulate   Local circuit simulation                                                                                  │
│            CLI Docs  |  GitHub                                                                                       │
│ submit     Submit circuits to quantum cloud platforms                                                                │
│            CLI Docs  |  GitHub                                                                                       │
│ result     Query task results from quantum cloud platforms                                                           │
│            CLI Docs  |  GitHub                                                                                       │
│ doctor     Run diagnostics to verify your uniqc installation                                                         │
│            CLI Docs  |  GitHub                                                                                       │
│ config     Manage API key and configuration                                                                          │
│            CLI Docs  |  GitHub                                                                                       │
│ task       Manage submitted tasks                                                                                    │
│            CLI Docs  |  GitHub                                                                                       │
│ backend    List, update, and inspect quantum cloud backends                                                          │
│            CLI Docs  |  GitHub                                                                                       │
│ calibrate  Run chip calibration experiments — XEB benchmarking (1q/2q/parallel), readout error calibration, and      │
│            parallel execution pattern analysis. Results are cached to ~/.uniqc/calibration_cache/ with TTL freshness │
│            enforcement.                                                                                              │
│            CLI Docs  |  GitHub                                                                                       │
│ gateway    Manage the uniqc gateway web UI server.                                                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯


== uniqc backend list (dummy only; cloud backends require credentials) ==
                               Available Backends                               
╭────────────┬──────────────────────────────┬──────────┬──────────────┬────────╮
│ Platform   │ Name                         │   Qubits │ Status       │ Type   │
├────────────┼──────────────────────────────┼──────────┼──────────────┼────────┤
│ dummy      │ dummy:local:simulator        │        - │ available    │ sim    │
│ dummy      │ dummy:local:virtual-line-3   │        3 │ available    │ sim    │
│ dummy      │ dummy:local:virtual-grid-2x2 │        4 │ available    │ sim    │
│ dummy      │ dummy:local:mps-linear-3     │        3 │ available    │ sim    │
╰────────────┴──────────────────────────────┴──────────┴──────────────┴────────╯

Cache:
    originq: 6 backends, updated 11h ago
    quafu: 16 backends, updated 19d ago (stale)
    ibm: 3 backends, updated 11h ago

== uniqc simulate bell.originir --shots 256 ==
      Simulation Results       
┏━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━┓
┃ State ┃ Count ┃ Probability ┃
┡━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━┩
│ 00    │ 127   │ 50.0%       │
│ 11    │ 127   │ 50.0%       │
└───────┴───────┴─────────────┘

== uniqc submit bell.originir --backend dummy -s 64 --wait --format json ==
{
  "task_id": "uqt_92115352805e495aa66e49c981308252",
  "backend": "dummy:local:simulator",
  "shots": 64
}
{
  "counts": {
    "00": 32,
    "11": 32
  },
  "probabilities": {
    "00": 0.5,
    "11": 0.5
  },
  "shots": 64,
  "platform": "dummy",
  "task_id": "uqt_92115352805e495aa66e49c981308252",
  "backend_name": "dummy:local:simulator",
  "execution_time": null,
  "error_message": null
}

== uniqc task list (most recent few) ==
                                                         Tasks                                                          
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ Task ID                              ┃ Platform                              ┃ Status  ┃ Shots ┃ Submit Time         ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ uqt_92115352805e495aa66e49c981308252 │ dummy:local:simulator                 │ success │ 64    │ 2026-05-17T23:26:45 │
│ uqt_ed3f17897c5f44c88fd8696722ae7d50 │ dummy:local:simulator                 │ success │ 64    │ 2026-05-17T23:26:30 │
│ uqt_eae7e360b52a40f28686206ebb385441 │ dummy:local:simulator                 │ success │ 128   │ 2026-05-17T23:26:27 │
│ uqt_bdcbb90a4194447d9e8e02cf876029c6 │ dummy:local:mps-linear-32:chi=8:cuto… │ success │ 400   │ 2026-05-17T23:26:26 │
│ uqt_ddef6695275449a0b0762ace7686fe6a │ dummy:local:mps-linear-3:chi=8        │ success │ 256   │ 2026-05-17T23:26:09 │
└──────────────────────────────────────┴───────────────────────────────────────┴─────────┴───────┴─────────────────────┘

子命令一览¶

命令	说明	详细文档
`uniqc --help`	顶层帮助，列出所有子命令	CLI 介绍
`uniqc simulate <file> [--shots N] [--backend <id>]`	本地模拟 OriginIR / QASM 文件	`uniqc simulate`
`uniqc submit <file> -b <provider:chip> [-s <shots>] [--wait]`	提交线路；`-b dummy:local:simulator` 用本地 dummy；真平台需配 token	`uniqc submit`
`uniqc submit ... --dry-run`	离线校验（不真的提交）	`uniqc submit`
`uniqc result <task_id>`	查询 / 取回单个任务结果	`uniqc result`
`uniqc task list / show / ...`	本地任务历史（SQLite at `~/.uniqc/tasks.db`）	`uniqc task`
`uniqc backend list / show / update`	后端发现与缓存（`~/.uniqc/backend-cache/`）	`uniqc backend`
`uniqc backend chip-display <id>`	全屏可视化芯片标定（T1/T2、保真度、拓扑）	`uniqc backend`
`uniqc config init / set / get / validate`	配置文件管理（`~/.uniqc/config.yaml`）	`uniqc config`
`uniqc calibrate xeb / readout / pattern`	芯片标定 → 写入 `~/.uniqc/calibration_cache/`	`uniqc calibrate`
`uniqc circuit ...`	电路文件转换 / 检查	`uniqc circuit`
`uniqc doctor`	一键环境诊断：依赖、配置、缓存、网络连通性	`uniqc doctor`
`uniqc gateway --host ... --port ...`	启动 WebUI / FastAPI 网关	`uniqc gateway` · WebUI

帮助文本里都附带了对应文档的 URL；加 --ai-hints 选项（或环境变量 UNIQC_AI_HINTS=1）会输出额外的 AI 工作流提示。

Dummy backend id 命名¶

CLI -p / -b 跟 Python API backend=... 共用同一套 id 文法（详见进阶教程 · Dummy 系统）：

id	含义
`dummy` / `dummy:local:simulator`	完全无约束、无噪声
`dummy:local:virtual-line-N`	虚拟线性拓扑、无噪声
`dummy:local:virtual-grid-RxC`	虚拟网格拓扑、无噪声
`dummy:local:mps-linear-N[:chi=K[:cutoff=E][:seed=S]]`	MPS 引擎，线性拓扑
`dummy:<platform>:<backend>`	复用真实芯片拓扑 + 标定噪声

CLI 完整 walkthrough¶

01 — CLI walkthrough: all the uniqc subcommands¶

子命令一览¶

Dummy backend id 命名¶

01 — CLI walkthrough: all the `uniqc` subcommands¶