qcoscloud CLI: SoftQuantus compute from the terminal

The qcoscloud CLI is the az-style command line for SoftQuantus compute: credits, instances, and GPU/CPU/simulation workloads on one prepaid wallet. It ships with the Python SDK package and wraps the same live REST API.

The API requires every QUANTUM_CIRCUIT workload to carry a circuit — pass --qasm circuit.qasm to run/simulate, or the platform rejects the request with 422 quantum_circuit_missing (protecting you from paying for an empty run).

Install and authenticate

PyPI publishing is in progress — until the release lands, drive the same operations over the REST API. The qcoscloud command is registered as a console script by the package:

pip install qcoscloud                                    # once the PyPI release is live

export QCOSCLOUD_API_KEY=sq-live-...                     # console → API Keys
export QCOSCLOUD_URL=https://platform.softquantus.com    # optional; default
qcoscloud credits

Output is pretty-printed JSON (except credits), so it pipes cleanly into jq.

Command summary

Command	Purpose
`qcoscloud credits`	Show the prepaid balance
`qcoscloud computers`	List QPU devices reachable via QCOS
`qcoscloud targets`	List compute activated for your workspace
`qcoscloud instances`	List quantum instances
`qcoscloud instances create NAME [flags]`	Create a quantum instance
`qcoscloud simulate --qasm FILE [flags]`	Run a circuit on the free simulator
`qcoscloud run --target ... --qasm FILE [flags]`	Submit a workload to a target
`qcoscloud gpu --type ... --command ... [flags]`	Run an on-demand GPU job
`qcoscloud cpu --tier ... --command ... [flags]`	Run an on-demand CPU job
`qcoscloud workload ID`	Show one workload
`qcoscloud evidence ID`	Show a settled workload’s evidence bundle
`qcoscloud workloads`	List recent workloads

credits

qcoscloud credits

$125.00 (12500 credits)

computers / targets

qcoscloud computers      # QPU devices reachable via QCOS
qcoscloud targets        # everything activated for your workspace (sim, cpu.*, gpu.*, QPUs)

targets also activates the workspace’s default catalog (simulator + GPU/CPU tiers) on first call — run it once from a fresh workspace.

instances

qcoscloud instances                       # list
qcoscloud instances create research \
  --plan prepaid \
  --qpus qcos.simulator.statevector,gpu.a100-80gb \
  --access-group all_members

Flag	Default	Values
`--plan`	`prepaid`	`free` · `prepaid` · `paygo`
`--qpus`	(empty = all entitled)	comma-separated target ids
`--access-group`	`all_members`	`all_members` · `owners_only` · `custom`

See Quantum instances for what plans and access groups mean (paygo requires prior approval).

run / simulate

qcoscloud simulate --qasm bell.qasm --shots 1000 --instance research

qcoscloud run --target <target-id> --qasm bell.qasm --shots 2000 \
  --instance research --mode NATIVE --max-cost-usd 5.0

Flag (`run`)	Default	Notes
`--target`	(required)	backend id
`--qasm`	(none)	OpenQASM circuit file; required for circuit targets
`--shots`	`1000`	number of shots
`--instance`	(workspace default billing)	instance id
`--mode`	`NATIVE`	`NATIVE` · `QCOS_OPTIMIZED` (needs a QCOS license)
`--max-cost-usd`	(none)	reject before running if the estimate exceeds this
`--max-runtime-seconds`	(none)	runtime bound

simulate takes --qasm, --shots and --instance.

workload / evidence

qcoscloud workload job_...     # status, billing mode, cost so far
qcoscloud evidence job_...     # evidence bundle once the job settled

gpu

Run a container command on an on-demand NVIDIA GPU. A runtime bound (--minutes) is always applied — the worst case is reserved up front and the GPU is stopped when the reservation is exhausted:

qcoscloud gpu --type a100-80gb --command "python train.py" --minutes 30 --num-gpus 1

Flag	Default	Notes
`--type`	(required)	`t4` · `l4` · `a10g` · `a100-40gb` · `a100-80gb` · `h100` → target `gpu.<type>`
`--command`	(required)	command to run in the container
`--minutes`	`60`	runtime bound (reserved worst case)
`--num-gpus`	`1`	GPUs to attach (multiplies the rate)
`--instance`	(workspace default billing)	instance id
`--image`	(provider default)	container image

If GPU capacity is not available for your workspace this fails closed with gpu_provider_unavailable and holds no money — see Backends & pricing.

cpu

Run a container command on on-demand CPUs (large/long simulations), billed per minute with a reserved runtime bound:

qcoscloud cpu --tier 16vcpu --command "python big_sim.py" --minutes 60 --cpus 16

Flag	Default	Notes
`--tier`	(required)	`4vcpu` · `8vcpu` · `16vcpu` · `32vcpu-highmem` → target `cpu.<tier>`
`--command`	(required)	command to run
`--minutes`	`60`	runtime bound
`--cpus`	(tier default)	vCPUs to attach
`--instance`	(workspace default billing)	instance id
`--image`	(provider default)	container image

workload / workloads

qcoscloud workload job_a1b2c3d4     # one job's status + cost
qcoscloud workloads                 # recent runs

Exit codes

Code	Meaning
`0`	Success
`1`	The platform rejected the call — stderr shows `error: ... <reason>. <hint>`
`2`	No API key (`QCOSCLOUD_API_KEY` unset)

Scripting example

# submit a bounded GPU job and wait for it to settle
id=$(qcoscloud gpu --type t4 --command "python train.py" --minutes 15 | jq -r .job_id)
until [ "$(qcoscloud workload "$id" | jq -r .status)" = "SETTLED" ]; do sleep 10; done
qcoscloud workload "$id" | jq '{status, actual_cost_usd, result_verified}'

Console

Run compute

API & clients

Trust & ecosystem

qcoscloud CLI: SoftQuantus compute from the terminal

Install and authenticate

Command summary

credits

computers / targets

instances

run / simulate

workload / evidence

gpu

cpu

workload / workloads

Exit codes

Scripting example

​Install and authenticate

​Command summary

​credits

​computers / targets

​instances

​run / simulate

​workload / evidence

​gpu

​cpu

​workload / workloads

​Exit codes

​Scripting example

Install and authenticate

Command summary

credits

computers / targets

instances

run / simulate

workload / evidence

gpu

cpu

workload / workloads

Exit codes

Scripting example