@kvantiqstudio/cli
v0.1.0-alpha.6
Published
Kvantiq Studio CLI - manage challenges, submissions, and scoring from the terminal
Maintainers
Readme
@kvantiqstudio/cli
The official command-line interface for Kvantiq Studio. Pull challenges, run them locally, and submit solutions without leaving your terminal.
npm install -g @kvantiqstudio/cli
kvantiq login
kvantiq quickstart qaoa-maxcut-optimizationThree binaries ship with the package: kvantiq, kvs, and kv. They are
interchangeable — pick whichever your fingers prefer.
Install
Install the CLI from npm:
npm install -g @kvantiqstudio/cliThen sign in:
kvantiq loginThe kvantiq, kvs, and kv binaries are interchangeable and ship from the
same package.
Requirements
- Node.js 20 or newer
- A Kvantiq Studio account — request access if you don't have one yet (the platform is currently invite-only)
- Docker (only required for
kvantiq run— local evaluation)
Authentication
kvantiq login opens your browser, signs you in via Kvantiq's PKCE magic-link
flow, and stores the resulting token in your operating system's credential
vault:
- macOS → Keychain
- Windows → Credential Manager
- Linux → libsecret (GNOME Keyring / KWallet)
Tokens are never written to a config file. kvantiq logout removes them from
the vault.
If you're on a headless server or SSH session, the CLI detects the lack of a TTY and prints a URL you can copy to a browser on another machine.
The short version
After kvantiq pull <slug>, the CLI creates a challenge.json file in the
challenge directory. From inside that directory, most commands know which
challenge you're working on — you don't have to type the slug again:
kvantiq pull qaoa-maxcut-optimization
cd qaoa-maxcut-optimization
kvantiq validate solution.py # checks your file
kvantiq run # runs the scoring pipeline locally
kvantiq submit solution.py # uploads and queues for scoring
kvantiq status --watch # follows the scoring jobCommon commands
| Command | What it does |
| --- | --- |
| kvantiq login | Sign in — opens browser, stores token in OS keychain |
| kvantiq logout | Remove stored credentials |
| kvantiq whoami | Show the email of the currently-logged-in account |
| kvantiq challenges list | List open challenges |
| kvantiq challenges show <slug> | Print full details for one challenge |
| kvantiq pull <slug> | Download starter files into the current directory |
| kvantiq quickstart <slug> | pull + create a marimo notebook in one step |
| kvantiq run | Run your solution locally in a Docker sandbox |
| kvantiq validate <file> | Check your solution file before submitting |
| kvantiq submit <file> | Upload a solution and queue it for scoring |
| kvantiq status | Show your latest submission's scoring status |
| kvantiq leaderboard <slug> | Print the leaderboard for a challenge |
| kvantiq marimo init <slug> | Generate a marimo notebook for a challenge |
| kvantiq config profile | View or change CLI configuration |
| kvantiq feedback | Send feedback to the Kvantiq team |
| kvantiq --help | Full command reference |
Run any command with --help for its full flag list.
Web and CLI are equals
Every feature of the CLI has a mirror in the Kvantiq Studio web app, and vice versa. Use whichever fits your workflow. The CLI is built for people who live in terminals, scripts, and CI pipelines — not as a cut-down companion.
Verbose and debug output
--verboseon any command prints HTTP request/response detailsDEBUG=kvantiq*environment variable enables low-level debug logs
Plugins
The CLI is built on oclif and supports third-party plugins.
The @kvantiqstudio/plugin-* namespace is reserved for official extensions. Install
a plugin with:
kvantiq plugins install @kvantiqstudio/plugin-<name>License
Apache License 2.0 — see LICENSE for the full text.
