Metadata-Version: 2.4
Name: qubecli
Version: 1.1.17
Summary: QubeCore CLI — Command Line Interface for QubeCore
License: MIT License
        
        Copyright (c) 2026 QubeCore Project
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: qubecore-client>=1.1.12
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# QubeCLI

QubeCore를 위한 커맨드라인 인터페이스입니다.  
게이트 회로 제출, 잡 상태 조회, QPU 캘리브레이션 관리 등 QubeCore의 모든 기능을 터미널에서 사용할 수 있습니다.

---

## 사전 조건

- Python 3.11 이상
- 실행 중인 QubeCore gRPC 서버

---

## 설치

```bash
pip install qubecli
```

---

## 커맨드 레퍼런스

### 전역 옵션

| 커맨드 / 옵션 | 설명 |
|------|------|
| `qubecli` | 배너 출력 (버전 및 사용 가능한 커맨드 안내) |
| `qubecli -v` / `--version` | 버전 출력 |

---

### 서버 연결

#### `qubecli connect <host[:port]>`

QubeCore 서버에 연결하고 주소를 저장합니다. 연결에 실패하면 에러를 출력합니다.

```bash
qubecli connect localhost:50051
qubecli connect 192.168.1.100:50051
qubecli connect myserver.com
```

---

### 인증

#### `qubecli login`

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--username` | string | (프롬프트) | 사용자 이름 |
| `--password` | string | (프롬프트) | 비밀번호 (입력 시 숨김 처리) |

```bash
qubecli login
qubecli login --username admin --password Admin1234!
```

#### `qubecli logout`

```bash
qubecli logout
```

#### `qubecli me`

```bash
qubecli me
#   user_id    : 1
#   username   : admin
#   role       : admin
#   created_at : 2026-01-01T00:00:00Z
```

---

### QPU 정보

#### `qubecli qpu-info`

```bash
qubecli qpu-info
#   name                 : kreo.sc-20
#   num_qubits           : 20
#   native_gates         : ['X90', 'CNOT', 'Y-90', 'Z90', 'CZ']
#   qasm_supported_gates : ['x', 'rx', 'y', 'ry', 'z', 'rz', 'h', 'cx', 'cz']
#   coupling_topology    : 00--01--02--03
#                           |\ /|\ /|\ /|
#                           |/ \|/ \|/ \|
#                          04--05--06--07
#                          ...
```

#### `qubecli qubit-info`

```bash
qubecli qubit-info
#   last_calibrated : 2026-05-13 09:00:00 KST
#   index  t1           t2           frequency       readout_fidelity   gate_fidelity
#   ────── ──────────── ──────────── ────────────── ────────────────── ─────────────
#   0      1.10e-04     9.80e-05     4.8500e+09      0.950              0.980
#   1      1.05e-04     9.20e-05     4.7200e+09      —                  —
```

---

### 잡 관리

#### `qubecli status`

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--job-id` | string | 필수 | 잡 ID |

```bash
qubecli status --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

#### `qubecli result`

```bash
qubecli result --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
#   job_id : a1b2c3d4-e5f6-7890-abcd-ef1234567890
#   status : COMPLETED
#   [circuit 0] counts : {'00': 512, '11': 488}
```

#### `qubecli cancel`

PENDING 상태의 잡을 취소합니다.

```bash
qubecli cancel --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

#### `qubecli jobs`

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--page` | int | 1 | 페이지 번호 (1-based) |
| `--size` | int | 20 | 페이지당 결과 수 |

```bash
qubecli jobs
qubecli jobs --page 2 --size 10
```

---

### 잡 제출

#### `qubecli submit-gate`

게이트 회로를 QPU에 제출합니다. 서버가 prefix를 보고 자동으로 포맷을 감지합니다.

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--circuit` | string | 필수 | 회로 문자열 (OpenQASM 2.0 / 3.0 / QIR / JSON) |
| `--shots` | int | 필수 | 측정 횟수 |
| `--priority` | 1–4 | 3 | 잡 우선순위 |
| `--optimization-level` | 0–3 | — | 트랜스파일 최적화 레벨 (**QIR 입력에는 적용되지 않음**) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

지원 포맷별 감지 규칙:

| 포맷 | 감지 기준 |
|------|----------|
| OpenQASM 2.0 | `OPENQASM 2` 로 시작 |
| OpenQASM 3.0 | `OPENQASM 3` 로 시작 |
| QIR (LLVM IR) | `__quantum__`, `target triple`, `; ModuleID`, `target datalayout`, `source_filename` 중 하나가 첫 2 KB 안에 존재 |
| JSON (pulse) | `{` 또는 `[` 로 시작 |

**OpenQASM 2.0 예제**

```bash
qubecli submit-gate \
  --circuit 'OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q->c;' \
  --shots 1000

qubecli submit-gate \
  --circuit 'OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q->c;' \
  --shots 1000 --priority 2 --optimization-level 1
```

**OpenQASM 3.0 예제**

```bash
qubecli submit-gate \
  --circuit 'OPENQASM 3; include "stdgates.inc"; qubit[2] q; bit[2] c; h q[0]; cx q[0],q[1]; c[0]=measure q[0]; c[1]=measure q[1];' \
  --shots 1000
```

**QIR 예제** (LLVM IR — 파일로 입력 권장)

```bash
# --circuit-file 옵션 사용 (권장)
qubecli submit-gate --circuit-file bell.ll --shots 1000

# 또는 파일 내용을 인라인으로
qubecli submit-gate --circuit "$(cat bell.ll)" --shots 1000
# --optimization-level 은 QIR 입력에는 적용되지 않음 (지정해도 무시됨)
```

> **셸 쿼트 주의**: `--circuit` 값에 싱글쿼트(`'`)가 포함된 경우 셸 파싱이 깨집니다.
> 이 경우 `--circuit-file`로 파일을 전달하거나, `$'...'` 구문을 사용하세요.
>
> ```bash
> # 싱글쿼트 포함 시
> qubecli submit-gate --circuit-file my_circuit.qasm --shots 100
> ```

**파라메트릭 스윕**

`--params` 옵션을 추가하면 파라메트릭 스윕 모드로 동작합니다. 회로 내 `{param}` 플레이스홀더에 파라미터 배열을 순차 치환하여 스트리밍으로 실행하고 결과를 즉시 반환합니다.

> **주의**: QIR은 파라메트릭 스윕과 함께 사용할 수 없습니다. OpenQASM 2.0 / 3.0을 사용하세요.

| 추가 옵션 | 타입 | 설명 |
|-----------|------|------|
| `--params` | JSON array | 파라미터 딕셔너리 배열. `{param}` 플레이스홀더가 circuit에 있어야 함 |

```bash
qubecli submit-gate \
  --circuit 'OPENQASM 2.0; include "qelib1.inc"; qreg q[1]; creg c[1]; rx({theta}) q[0]; measure q[0]->c[0];' \
  --params '[{"theta": 0.0}, {"theta": 1.5707}, {"theta": 3.1415}]' \
  --shots 200
# Parametric sweep: 3 iteration(s) → shots=200
#   [1/3] counts={'0': 200}
#   [2/3] counts={'0': 102, '1': 98}
#   [3/3] counts={'1': 200}
```

#### `qubecli submit-pulse`

백엔드 전용 펄스 프로그램을 제출합니다.

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--pulse` | string | 필수 | 펄스 프로그램 JSON 문자열 |
| `--shots` | int | 필수 | 측정 횟수 |
| `--priority` | 1–4 | 3 | 잡 우선순위 |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli submit-pulse \
  --pulse '[{"name":"X90","qubit":"qubit_0"},{"name":"read","qubit":"qubit_0"}]' \
  --shots 1000
```

#### `qubecli reset`

큐비트 액티브 리셋 잡을 제출합니다.

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--qubits` | string | — | 쉼표로 구분된 큐비트 이름. 생략 시 전체 큐비트 reset |
| `--shots` | int | 필수 | 리셋 후 검증 측정 횟수 |
| `--priority` | 1–4 | 3 | 잡 우선순위 |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
# 특정 큐비트 reset
qubecli reset --qubits qubit_0,qubit_1 --shots 100

# 전체 큐비트 reset
qubecli reset --shots 100
```

### `qubecli calibration`

캘리브레이션 잡을 제출합니다. 타입에 따라 서브커맨드를 사용합니다.


#### `qubecli calibration widescan`

주파수 범위 스캔 캘리브레이션 잡을 제출합니다.

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--freq-span` | float | O | 주파수 스캔 범위 (Hz) |
| `--n-freqs` | int | O | 스캔 포인트 수 |
| `--shots` | int | O | 포인트당 측정 횟수 |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration widescan --qubit qubit_0 --freq-span 100000000 --n-freqs 200 --shots 100
```

#### `qubecli calibration punchout`

Readout Amplitude 스캔 캘리브레이션 잡을 제출합니다.

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--amps` | JSON array | O | 스캔할 진폭 리스트 |
| `--freq-span` | float | O | 주파수 스캔 범위 (Hz) |
| `--n-freqs` | int | O | 주파수 포인트 수 |
| `--shots` | int | O | 포인트당 측정 횟수 |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration punchout --qubit qubit_0 --amps '[0.01,0.05,0.1,0.2,0.3,0.5]' \
  --freq-span 20000000 --n-freqs 20 --shots 100
```

#### `qubecli calibration chevron`

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--freq-span` | float | O | 주파수 스캔 범위 (Hz) |
| `--n-freqs` | int | O | 주파수 포인트 수 |
| `--x-twidth` | JSON array | O | 펄스 폭 리스트 (s) |
| `--shots` | int | O | 포인트당 측정 횟수 |
| `--center-freq` | float | — | 중심 주파수 (Hz, 선택) |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration chevron --qubit qubit_0 --freq-span 1000000 --n-freqs 20 \
  --x-twidth '[1e-8,2e-8,3e-8]' --shots 100
```

#### `qubecli calibration amp-rabi`

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--target-twidth` | float | — | 목표 펄스 폭 (s, 선택) |
| `--n-amps` | int | O | 진폭 분할 수 |
| `--shots` | int | O | 포인트당 측정 횟수 |
| `--amp-range-min` | float | — | 진폭 범위 최솟값 (기본값: 0.0) |
| `--amp-range-max` | float | — | 진폭 범위 최댓값 (기본값: 1.0) |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration amp-rabi --qubit qubit_0 --n-amps 20 --shots 100
```

#### `qubecli calibration time-rabi`

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--shots` | int | O | 포인트당 측정 횟수 |
| `--x-twidth` | JSON array | — | 펄스 폭 리스트 (s, 선택) |
| `--target-amplitude` | float | — | 목표 진폭 (선택) |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration time-rabi --qubit qubit_0 --shots 100
qubecli calibration time-rabi --qubit qubit_0 --shots 100 --x-twidth '[1e-8,2e-8,3e-8]'
```

#### `qubecli calibration ramsey`

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--delay-interval` | JSON array | O | 딜레이 간격 리스트 (s) |
| `--shots` | int | O | 포인트당 측정 횟수 |
| `--framsey-offsets` | JSON array | — | Framsey 오프셋 리스트 (선택) |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration ramsey --qubit qubit_0 --delay-interval '[1e-6,2e-6,3e-6]' --shots 100
```

#### `qubecli calibration t1`

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--delay-interval` | JSON array | O | 딜레이 간격 리스트 (s) |
| `--shots` | int | O | 포인트당 측정 횟수 |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration t1 --qubit qubit_0 --delay-interval '[1e-6,2e-6,5e-6,1e-5]' --shots 100
```

#### `qubecli calibration stack-x90`

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--shots` | int | O | 포인트당 측정 횟수 |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration stack-x90 --qubit qubit_0 --shots 100
```

#### `qubecli calibration drag-alpha`

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--shots` | int | O | 포인트당 측정 횟수 |
| `--alphas` | JSON array | — | Alpha 값 리스트 (선택) |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration drag-alpha --qubit qubit_0 --shots 100
qubecli calibration drag-alpha --qubit qubit_0 --shots 100 --alphas '[-0.5,-0.3,0.0,0.3,0.5]'
```

#### `qubecli calibration blob-readout-freq`

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--shots` | int | O | 포인트당 측정 횟수 |
| `--dfreads` | JSON array | — | Readout 주파수 오프셋 리스트 (선택) |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration blob-readout-freq --qubit qubit_0 --shots 100
qubecli calibration blob-readout-freq --qubit qubit_0 --shots 100 --dfreads '[-1e6,0,1e6]'
```

#### `qubecli calibration readout-fidelity`

Readout 신뢰도(readout fidelity) 측정 잡을 제출한다.

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--shots` | int | O | 측정 횟수 |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration readout-fidelity --qubit qubit_0 --shots 100
```

#### `qubecli calibration gate-fidelity`

Randomized Benchmarking(RB)으로 게이트 신뢰도(gate fidelity) 측정 잡을 제출한다.

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubit` | string | O | 큐비트 이름 |
| `--shots` | int | O | 시퀀스당 측정 횟수 |
| `--lengths` | JSON array | — | RB 게이트 길이 (예: `[1,2,4,8,16,32]`) |
| `--n-seeds` | int | — | RB 랜덤 시드 수 (기본값: 서버 설정) |
| `--seed-base` | int | — | 랜덤 시드 기준값 (선택) |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 3=NORMAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, 300초 타임아웃) |

```bash
qubecli calibration gate-fidelity --qubit qubit_0 --shots 100
qubecli calibration gate-fidelity --qubit qubit_0 --shots 100 --lengths '[1,2,4,8,16,32]' --n-seeds 5
```

#### `qubecli calibration full`

Admin 전용. 큐비트 파라미터를 처음부터 최적화하는 **전체 캘리브레이션**을 실행합니다. 장비 초기 셋업 또는 파라미터가 크게 틀어진 경우에 사용합니다.

**실행 순서 (큐비트별 순차):**

| 단계 | 이름 | 목적 |
|------|------|------|
| 1 | `widescan` | 큐비트 주파수 대역 탐색 |
| 2 | `punchout` | Readout resonator 주파수/파워 최적화 |
| 3 | `amp_rabi` | X90 펄스 진폭(π펄스 amplitude) 최적화 |
| 4 | `time_rabi` | X90 펄스 길이(π펄스 duration) 최적화 |
| 5 | `blob_readout_freq` | Readout 주파수 fine-tuning |
| 6 | `drag_alpha` | DRAG 펄스 alpha 파라미터 최적화 |
| 7 | `stack_x90` | X90 오차 누적 측정 및 보정 |
| 8 | `readout_fidelity` | Readout 충실도 측정 및 저장 |
| 9 | `gate_fidelity` | 게이트 충실도 측정 (Clifford RB) |

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubits` | string | — | 쉼표로 구분된 큐비트 이름 (예: `qubit_0,qubit_1`). 생략 시 전체 큐비트 |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 1=CRITICAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 결과 출력 (3초 폴링, **7200초** 타임아웃) |

```bash
# 전체 큐비트 full calibration
qubecli calibration full

# 특정 큐비트만
qubecli calibration full --qubits qubit_0,qubit_1
```

---

#### `qubecli calibration characterization`

Admin 전용. 파라미터가 이미 최적화된 상태에서 큐비트 물성값(T1, T2, readout/gate fidelity)을 주기적으로 측정·갱신합니다.

**실행 순서 (큐비트별 순차):**

| 단계 | 이름 | 목적 |
|------|------|------|
| 1 | `readout_fidelity` | Readout 충실도 측정 |
| 2 | `t1` | 에너지 이완 시간(T1) 측정 |
| 3 | `ramsey` | T2* 및 주파수 드리프트 측정 |
| 4 | `gate_fidelity` | 게이트 충실도 측정 (Clifford RB) |

| 옵션 | 타입 | 필수 | 설명 |
|------|------|:----:|------|
| `--qubits` | string | — | 쉼표로 구분된 큐비트 이름 (예: `qubit_0,qubit_1`). 생략 시 전체 큐비트 측정 |
| `--priority` | 1–4 | — | 잡 우선순위 (기본값: 1=CRITICAL) |
| `--wait` | flag | — | 잡 완료까지 대기 후 캐릭터라이제이션 테이블 출력 (3초 폴링, **3600초** 타임아웃) |

```bash
# 전체 큐비트 측정
qubecli calibration characterization
# ✓ Job submitted
#   job_id           : a1b2c3d4-e5f6-7890-abcd-ef1234567890
#   calibration_type : characterization
#   priority         : CRITICAL

# 특정 큐비트만 측정
qubecli calibration characterization --qubits qubit_0,qubit_1
```
