CLI-QCOS - QCOS™ Command Line Interface

QCOS™ CLI — Command-line interface for the Quantum Circuit Optimization Service by SoftQuantus.

📦 Installation

pip install softqcos

This will automatically install the softqcos-sdk dependency.

🚀 Quick Start

# Configure API access once. No shell export required.
softqcos login

# Verify local config and API connectivity
softqcos doctor

# Show the SoftQuantus product welcome screen
softqcos welcome

# Show help
softqcos --help

# Run GHZ state optimization
softqcosrun ghz --qubits 20 --max-iters 100

# Run benchmark
softqcosbenchmark --qubits 5,10,20,50 --backend aer

# Show version
softqcos --version

# Show system info
softqcos info

The CLI stores credentials in ~/.softqcos/config.json with file mode 0600. QCOS_API_KEY and QCOS_API_URL still work and override the saved config for CI/CD jobs.

📋 Commands

softqcosrun

Run quantum circuit optimization.

softqcosrun ghz --qubits 50 --max-iters 100 --backend aer
softqcosrun vqe --qubits 4 --cost energy

Options:

• --qubits, -q: Number of qubits (default: 10)
• --max-iters, -i: Maximum iterations (default: 100)
• --backend, -b: Backend (aer, cirq, pennylane, braket)
• --method, -m: Backend method (automatic, statevector, matrix_product_state)
• --cost, -c: Cost function (correlation, bitstring, hybrid)
• --output, -o: Save results to JSON file

softqcosbenchmark

Run benchmarks across multiple qubit counts.

softqcosbenchmark --qubits 5,10,20,50 --backend aer --output results.json

softqcosinfo

Show system and environment information.

softqcosinfo

softqcos login

Configure the production API URL and API key interactively:

softqcos login

Non-interactive setup:

softqcos login \
  --api-url https://platform.softquantus.com \
  --api-key sq-live-...

Show config:

softqcos config

Reset config:

softqcos config --reset

Run diagnostics:

softqcos doctor

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

softqcosversion

Show version information.

softqcos--version

📄 License

QCOS™ is proprietary software by SoftQuantus innovative OÜ.

• EULA: https://softquantus.com/legal/eula
• Terms: https://softquantus.com/legal/terms
• Privacy: https://softquantus.com/legal/privacy

🏢 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-2025 SoftQuantus innovative OÜ. All Rights Reserved. QCOS™ is a trademark of SoftQuantus innovative OÜ.