Interfaz de línea de comandos

El SDK incluye un comando qc para flujos habituales desde terminal. Úsalo cuando quieras inspeccionar jobs, lanzar jobs, subir datasets o consultar casos de uso y solvers sin escribir un script de Python.

Instalación

Instala el paquete:

pip install qcentroid-sdk

Cuando desarrolles desde un checkout local, instálalo en modo editable desde la raíz del repositorio:

python -m pip install -e .

Después verifica que el comando está disponible:

qc --help

En Windows, si PowerShell no encuentra qc, añade al PATH de la terminal actual el directorio de scripts de usuario mostrado por pip install:

$env:PATH += ";$env:APPDATA\Python\Python313\Scripts"

Autenticación

La CLI usa las mismas variables de entorno que el cliente Python.

PowerShell:

$env:QCENTROID_API_KEY = "your-api-key"

macOS/Linux:

export QCENTROID_API_KEY="your-api-key"

También puedes pasar una API key para un único comando:

qc --api-key "your-api-key" jobs list

Si ya tienes un access token, usa:

export QCENTROID_TOKEN="your-access-token"

Seleccionar un entorno

El entorno por defecto es sandbox.

PowerShell:

$env:QCENTROID_ENVIRONMENT = "sandbox"

macOS/Linux:

export QCENTROID_ENVIRONMENT="sandbox"

También puedes pasar el entorno por comando:

qc --env dev jobs list

Los nombres de entorno soportados son sandbox, dev, prod y production.

Formato de salida

Por defecto, los comandos de listado imprimen una tabla legible.

Los comandos de listado que soportan paginación muestran hasta 10 filas por defecto. Usa --limit para solicitar un número diferente de filas.

Usa --json antes del nombre del recurso para imprimir JSON:

qc --json jobs list
qc --json jobs get my-job-name

Jobs

Listar jobs recientes:

qc jobs list

Limitar y filtrar jobs:

qc jobs list --limit 10
qc jobs list --status FINISHED
qc jobs list --tag my-tag

Obtener un job por nombre:

qc jobs get my-job-name

Esperar a que un job finalice:

qc jobs wait my-job-name

Controlar el intervalo de polling y el timeout:

qc jobs wait my-job-name --poll-interval 60 --timeout 3600

Leer la entrada, salida y logs de ejecución de un job:

qc jobs input my-job-name
qc jobs output my-job-name
qc jobs logs my-job-name

Ejecutar un job con datos JSON inline:

qc jobs run \
  --use-case my-use-case-name \
  --data '{"a": 2, "b": 3}' \
  --solver my-solver-name \
  --num-shots 1

Equivalente en PowerShell:

qc jobs run `
  --use-case my-use-case-name `
  --data '{"a": 2, "b": 3}' `
  --solver my-solver-name `
  --num-shots 1

Ejecutar un job con un archivo JSON:

qc jobs run \
  --use-case my-use-case-name \
  --data ./input.json \
  --solver my-solver-name \
  --num-shots 1

Ejecutar un job con un dataset existente:

qc jobs run \
  --use-case my-use-case-name \
  --dataset-id my-dataset-id \
  --solver my-solver-name \
  --num-shots 1

Algunos casos de uso requieren configuración adicional del solver. Pasa objetos JSON con:

qc jobs run \
  --use-case my-use-case-name \
  --dataset-id my-dataset-id \
  --solver my-solver-name \
  --solvers-provider-params '{"my-solver-name": {}}' \
  --max-exec-time-m 0

Casos de uso

Listar casos de uso disponibles:

qc use-cases list

Obtener el schema de un caso de uso:

qc use-cases schema my-use-case-name

Solvers

Listar solvers disponibles:

qc solvers list

Esto muestra hasta 10 solvers por defecto. Usa --limit y --skip para paginar más filas.

Listar solvers para un caso de uso concreto:

qc solvers list --use-case my-use-case-name

Datasets

Listar datasets:

qc datasets list

Subir un archivo de dataset:

qc datasets upload --use-case my-use-case-name ./data.json

Añadir metadatos al dataset:

qc datasets upload \
  --use-case my-use-case-name \
  --file-name my-dataset.json \
  --description "Input data for my use case" \
  ./data.json

Resolución de problemas

Si ves:

qc: No access token is available and an API key was not provided.

Define QCENTROID_API_KEY en la misma sesión de terminal donde ejecutas qc, o pasa --api-key directamente.

Si PowerShell indica que no reconoce qc, el paquete se instaló correctamente pero el directorio de scripts de Python no está en PATH. Usa la ruta completa a qc.exe mostrada por pip install, o añade ese directorio a PATH.