SoftQCOS CLI

The softqcos command talks to the QCOS REST API at https://api.softquantus.com. It has no privileges of its own: every command is a call to /api/v1/* made with your API key, and runs only what that API serves.

The CLI, the Python SDK (softqcos-sdk) and the MCP server (softqcos-mcp) are released together and always carry the same version number. The table at the end of this page lists what each version added.

Install

pip install softqcos
softqcos --version

The PyPI package is softqcos; it installs softqcos-sdk as a dependency. Python 3.10 or newer. Every command, including offline softqcos verify of RSA-PSS and Ed25519 seals, works from that plain install.

The extras forward to the SDK's:

pip install "softqcos[simulation]"   # Qiskit + Aer: run circuits locally
pip install "softqcos[pqc]"          # liboqs-python: verify ML-DSA (FIPS 204) seals
pip install "softqcos[all]"          # every SDK extra (qiskit, cirq, pennylane, ibm, braket, azure, pqc)

pqc installs liboqs-python, which is only the binding: the native liboqs shared library must be installed too, either by running python -c "import oqs" once (it downloads and builds liboqs into ~/_oqs; needs git, cmake and a C compiler) or by setting OQS_INSTALL_PATH to the prefix of a shared build. softqcos evidence verify never builds it for you; without it an ML-DSA seal reports signature_valid: None, with the reason.

Sign in

Create an API key at https://platform.softquantus.com/#apikeys, then:

softqcos auth login

auth login asks for the key, checks that https://api.softquantus.com/api/v1/status answers, and saves both in ~/.softqcos/config.json (file mode 0600). In CI, skip the file and set the environment instead:

export QCOS_API_KEY="<your key>"

Settings are resolved in this order: environment variable, then ~/.softqcos/config.json, then the default.

softqcos config                      # show what is stored
softqcos config set api_url https://api.softquantus.com
softqcos config --reset              # delete ~/.softqcos/config.json
softqcos auth status                 # key and license status
softqcos auth logout                 # release the local license

softqcos doctor checks the config file, the URLs, that a key is present, and that the API answers GET /api/v1/status. That route does not need a key, so a passing doctor does not prove the key is valid. The first authenticated command does.

First job, on a simulator

Save a Bell circuit as bell.qasm:

OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;

Ask for an estimate first. --dry-run executes nothing:

softqcos jobs submit --circuit bell.qasm --backend simulator_aer --shots 1024 --dry-run

Then submit, and read the result with the job id it prints:

softqcos jobs submit --circuit bell.qasm --backend simulator_aer --shots 1024
softqcos jobs status <job_id>
softqcos jobs results <job_id>
softqcos jobs list --limit 5

--backend defaults to simulator_aer. A QPU backend costs money: use --max-cost-usd to refuse a run above a ceiling, and --confirm-cost once you have read the estimate. Every command takes --json for scripts.

Commands

softqcos --help lists the root commands; every group has its own --help.

softqcos extensions holds the specialised domains: qec, network, calibration, chemistry, state, dynamics, evidence, qubo, science and more. Each of them also answers at the root (softqcos qec ...) for older scripts. Those root aliases are not listed in --help. New scripts should use softqcos extensions <group>.

Removed in 3.9.2: admin, macro, autopilot, nvqlink and zne. Every one of their commands called a route the API does not serve, so each answered 404.

softqcos srp needs the softqcos[srp] extra. That extra depends on softqcos-srp, which is not published on PyPI yet, so pip install "softqcos[srp]" fails today.

softqcos api

Stable JSON-first commands for agents, MCP bridges, Cursor, Copilot, and scripts:

softqcos api workspace init --json
softqcos api workspace discover --json
softqcos api job validate --input jobs/bell.qcos.json --json
softqcos api job plan --input jobs/bell.qcos.json --json
softqcos api run local --input jobs/bell.qcos.json --json
softqcos api result summary --input results/<run_id>/summary.json --json

These commands return structured payloads with status, capability, artifacts, metrics, and next_actions so AI agents can continue workflows reliably.

QCOS GPU planning commands:

softqcos api gpu detect --json
softqcos api gpu benchmark --input circuits/bell.qasm --json
softqcos api gpu engine-detect --json
softqcos api gpu estimate-memory --qubits 30 --precision fp64 --json
softqcos api gpu plan --input circuits/bell.qasm --json
softqcos api gpu simulate --input circuits/bell.qasm --fallback-aer --json
softqcos api backend plan --input circuits/bell.qasm --json
softqcos api backend compare --input circuits/bell.qasm --execute-aer --json
softqcos api hybrid detect --json
softqcos api hybrid qec-plan --code surface --distance 5 --rounds 3 --json
softqcos api qlink plan-feedback-loop --qpu lab-qpu-1 --latency-budget-us 100 --qec --json

softqcos generate

Structured content for games, design tools and simulations, expanded from a seed the runtime draws. The expansion is a named deterministic function, so anyone holding the seed digest can reproduce the output; nothing here is computed on a QPU and nothing here is faster because of quantum.

softqcos generate tasks
softqcos generate seed --seed-bytes 32
softqcos generate terrain --width 64 --height 64 --biomes 4
softqcos generate character --personality 8 --traits 8 --relationships 3
softqcos generate narrative-branch -o ally -o betray --weight 1 --weight 3
softqcos generate distribution --samples 1000 --shape normal

Every successful run prints where the entropy came from — the backend that answered, whether it was genuinely quantum, and the seed digest:

Provenance
  backend        cloud_ibm
  quantum        yes — a quantum source produced the seed
  entropy_bits   256.0
  expander       splitmix64/v1
  seed_sha256
    a1a1...

--quantum-required refuses classical entropy instead of substituting it: if no quantum source answers, the command fails, nothing is generated, and the error says so. Use it whenever the origin of the result will be claimed publicly.

softqcos generate terrain --quantum-required     # exits non-zero if no QPU entropy
softqcos generate terrain --json                 # full response, provenance included

softqcos extensions science

The Scientific Runtime (experimental): one contract for a scientific problem, a planner that says which solver fits it, and a result that carries its own validation. The algorithms are entries of one catalog, not separate products.

softqcos extensions science capabilities
softqcos extensions science algorithms --capability eigensolve --status available
softqcos extensions science algorithms --experimental-quantum
softqcos extensions science plan eigensolve --model transverse_field_ising --sites 4 --field 1.0 --tolerance 1e-3
softqcos extensions science eigensolve --model transverse_field_ising --sites 4 --field 1.0 --n-states 2
softqcos extensions science eigensolve --model transverse_field_ising --sites 4 --field 1.0 --algorithm vqe --seed 7
softqcos extensions science evolve --model transverse_field_ising --sites 4 --field 1.0 --total-time 2.0 --observable Z0=ZIII
softqcos extensions science optimize --problem qubo.json
softqcos extensions science simulate --model fermi_hubbard --sites 2 --interaction 4.0 --particle-number 2 --total-time 1.0
softqcos extensions science resource-estimate --model transverse_field_ising --sites 4 --field 1.0 --tolerance 1e-3
softqcos extensions science validate --model transverse_field_ising --sites 4 --field 1.0 --claimed-value -4.7588 --tolerance 1e-3

A problem is a JSON object: --problem FILE (- reads stdin), or a lattice model described with --model and --sites. A flag overrides the same field of the file. qubo.json above is {"qubo": {"linear": [-1.0, -2.0, 1.0], "quadratic": [[0, 1, 3.0], [1, 2, -2.0]]}}.

Every computation prints its verdict first:

eigensolve  algorithm=vqe  substrate=local_cpu_statevector  qubits=4  runtime=5.145139 s
validation: FAILED  |error|=0.01426626188  tolerance=1e-06  reference=exact_diagonalization

That run is the sixth command above, and the verdict is the point: the hardware-efficient ansatz at its default depth stops 1.4e-2 above the exact ground energy, and the runtime says so instead of returning a number that looks like an answer. A result that misses its tolerance is still a result — the API answers 200 and the command exits 0; read the status, or pass --json.

Nothing here reaches a QPU or a GPU. The quantum algorithms run on the API host's exact statevector simulator (16 qubits by default; capabilities prints the limits). plan lists what a problem would cost on hardware without running it. The catalog is larger than what executes: entries marked planned, experimental_quantum (VQLS, HHL, amplitude estimation) or resource_estimate_only (QPE, qubitization) are refused with the list of algorithms that do run. The catalog and the planner need a key with qcos:read; the computations need qcos:execute.

What each version added

Generated from the code at release time, so it cannot drift from what this version runs. Command paths as you type them.

Package version on this source tree: 3.11.1. softqcos-sdk, softqcos and softqcos-mcp always carry the same number, so the row a name sits in is the first version of THIS package that has it. A version is listed once it is tagged; it reaches PyPI when that release is published, and pip index versions softqcos shows which versions PyPI has.

Removed (no longer exists):

• softqcos admin: since <=3.8.0, removed in 3.9.2
• softqcos admin audit: since <=3.8.0, removed in 3.9.2
• softqcos admin backends-status: since <=3.8.0, removed in 3.9.2
• softqcos admin circuit-breakers: since <=3.8.0, removed in 3.9.2
• softqcos admin config: since <=3.8.0, removed in 3.9.2
• softqcos admin health: since <=3.8.0, removed in 3.9.2
• softqcos admin logs: since <=3.8.0, removed in 3.9.2
• softqcos admin metrics: since <=3.8.0, removed in 3.9.2
• softqcos admin rate-limits: since <=3.8.0, removed in 3.9.2
• softqcos admin tenants: since <=3.8.0, removed in 3.9.2
• softqcos admin usage: since <=3.8.0, removed in 3.9.2
• softqcos evidence artifacts: since <=3.8.0, removed in 3.8.3
• softqcos evidence capabilities: since <=3.8.0, removed in 3.8.3
• softqcos evidence download: since <=3.8.0, removed in 3.8.3
• softqcos evidence public-key: since <=3.8.0, removed in 3.8.3
• softqcos extensions autopilot: since <=3.8.0, removed in 3.9.2
• softqcos extensions autopilot execute: since <=3.8.0, removed in 3.9.2
• softqcos extensions autopilot plan: since <=3.8.0, removed in 3.9.2
• softqcos extensions autopilot recommend: since <=3.8.0, removed in 3.9.2
• softqcos extensions autopilot vendors: since <=3.8.0, removed in 3.9.2
• softqcos extensions macro: since <=3.8.0, removed in 3.9.2
• softqcos extensions macro energy-optimize: since <=3.8.0, removed in 3.9.2
• softqcos extensions macro health: since <=3.8.0, removed in 3.9.2
• softqcos extensions macro market-sizing: since <=3.8.0, removed in 3.9.2
• softqcos extensions macro risk-analysis: since <=3.8.0, removed in 3.9.2
• softqcos extensions provider-hub list: since <=3.8.0, removed in 3.9.2
• softqcos extensions provider-hub register: since <=3.8.0, removed in 3.9.2
• softqcos extensions provider-hub remove: since <=3.8.0, removed in 3.9.2
• softqcos extensions qlink: since <=3.8.0, removed in 3.9.2
• softqcos extensions qlink profile: since <=3.8.0, removed in 3.9.2
• softqcos extensions qlink simulate: since <=3.8.0, removed in 3.9.2
• softqcos extensions qlink status: since <=3.8.0, removed in 3.9.2
• softqcos extensions qlink transfer: since <=3.8.0, removed in 3.9.2
• softqcos extensions qubo energy-dispatch: since <=3.8.0, removed in 3.9.2
• softqcos extensions qubo portfolio: since <=3.8.0, removed in 3.9.2
• softqcos extensions zne: since <=3.8.0, removed in 3.9.2
• softqcos extensions zne mitigate: since <=3.8.0, removed in 3.9.2

License

Apache License, Version 2.0 — see LICENSE and NOTICE.

Copyright 2024-2026 SoftQuantus innovative OÜ (registry code 17048927, Tallinn, Estonia). QCOS™ and SoftQuantus™ are trademarks of SoftQuantus innovative OÜ; the license does not grant trademark rights. The QCOS service reached through this package is governed by the SoftQuantus Terms of Service, not by this license.

• Terms: https://softquantus.com/legal/terms
• Privacy: https://softquantus.com/legal/privacy
• Portal: https://platform.softquantus.com

Company

SoftQuantus innovative OÜ Registry Code: 17048927 Address: Veskiposti tn 2-1002, Tallinn, 10138, Estonia

Contact

• Support: support@softquantus.com
• Licensing: licensing@softquantus.com
• Legal: legal@softquantus.com

© 2024-2026 SoftQuantus innovative OÜ. All Rights Reserved. QCOS™ is a trademark of SoftQuantus innovative OÜ.