Command Line Interface

The SDK includes a qc command for common terminal workflows. Use it when you want to inspect jobs, launch jobs, upload datasets, or query use cases and solvers without writing a Python script.

Install

Install the package:

pip install qcentroid-sdk

When developing from a local checkout, install it in editable mode from the repository root:

python -m pip install -e .

Then verify the command is available:

qc --help

On Windows, if PowerShell cannot find qc, add the user scripts directory shown by pip install to PATH for the current terminal:

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

Authenticate

The CLI uses the same environment variables as the Python client.

PowerShell:

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

macOS/Linux:

export QCENTROID_API_KEY="your-api-key"

You can also pass an API key for one command:

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

If you already have an access token, use:

export QCENTROID_TOKEN="your-access-token"

Select an environment

The default environment is sandbox.

PowerShell:

$env:QCENTROID_ENVIRONMENT = "sandbox"

macOS/Linux:

export QCENTROID_ENVIRONMENT="sandbox"

You can also pass the environment per command:

qc --env dev jobs list

Supported environment names are sandbox, dev, prod, and production.

Output format

By default, list commands print a readable table.

List commands that support pagination show up to 10 rows by default. Use --limit to request a different number of rows.

Use --json before the resource name to print JSON:

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

Jobs

List recent jobs:

qc jobs list

Limit and filter jobs:

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

Get a job by name:

qc jobs get my-job-name

Wait for a job to finish:

qc jobs wait my-job-name

Control polling and timeout:

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

Read job input, output, and execution logs:

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

Run a job with inline JSON data:

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

PowerShell equivalent:

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

Run a job with a JSON file:

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

Run a job with an existing dataset:

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

Some use cases require additional solver configuration. Pass JSON objects with:

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

Use Cases

List available use cases:

qc use-cases list

Get the schema for a use case:

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

Solvers

List available solvers:

qc solvers list

This shows up to 10 solvers by default. Use --limit and --skip to page through more rows.

List solvers for a specific use case:

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

Datasets

List datasets:

qc datasets list

Upload a dataset file:

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

Add dataset metadata:

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

Troubleshooting

If you see:

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

Set QCENTROID_API_KEY in the same terminal session where you run qc, or pass --api-key directly.

If PowerShell says qc is not recognized, the package installed successfully but Python’s scripts directory is not on PATH. Use the full qc.exe path shown by pip install, or add that directory to PATH.