Command reference
The reference below is generated from the client's own command tree, so it matches stoa --help for the released version. Run stoa <command> --help for the same text in the terminal.
Global options
| Option | Description |
|---|---|
--debug | Print each request's method, path and status. |
--no-input | Never prompt: a command that would ask for a sign-in or a confirmation stops with its exit code instead (for scripts and coding agents). Environment variable STOA_. |
--version | Show the version and exit. |
-h, --help | Show this message and exit. |
agent-guide
Print the instructions a coding agent needs to drive this client (paste into CLAUDE.md).
assets search
stoa assets search [OPTIONS] TEXT...
Find catalog assets by name, slug or manufacturer.
| Option | Description |
|---|---|
--category TEXT | Restrict to one category slug. |
--json | Print the matching assets as JSON. |
categories
stoa categories [OPTIONS]
List asset categories and their grade ladders.
| Option | Description |
|---|---|
--json | Print the categories as JSON. |
login
stoa login [OPTIONS]
Sign in with email, password and a second-factor code (authenticator app or text message).
| Option | Description |
|---|---|
--email TEXT | Account email (prompted when omitted). |
logout
stoa logout [OPTIONS]
Forget the saved session for this environment.
| Option | Description |
|---|---|
--everywhere | Also sign out on the server. This ends every session you have, browser included. |
rfq create
stoa rfq create [OPTIONS]
Open an RFQ from a request file. A dry run validates the file against the venue and shows the composition it would freeze; the real create shows the same and asks you to agree to the binding statement before sending. A dry run needs a session too.
| Option | Description |
|---|---|
-f, --file PATH | TOML (or JSON) request file; start from stoa rfq template. Required. |
--dry-run | Have the server validate and show the composition; send nothing. |
--agree-binding-statement | Record your agreement to the binding statement and skip the prompt. For a person who has read a dry run; the statement is still printed. |
--idempotency-key UUID | Reuse a key from an earlier attempt so a retry can never create a second RFQ. |
--json | Print the composition or the created RFQ as JSON. |
rfq get
stoa rfq get [OPTIONS] RFQ_ID_OR_NUMBER
Show one RFQ by its id or its STOA-RFQ number: its configuration, dealers, every quote and its terms, and where to accept.
| Option | Description |
|---|---|
--json | Print the raw API response. |
rfq list
stoa rfq list [OPTIONS]
List your organisation's RFQs, newest first.
| Option | Description |
|---|---|
--status [DRAFT|ACTIVE|EXECUTED|EXPIRED|CANCELLED] | |
--limit INTEGER | 1 to 1000. Default 20. |
--json | Print the raw API items. |
rfq schema
stoa rfq schema [OPTIONS]
Print the request vocabulary the server publishes: every field, its type and its rules.
| Option | Description |
|---|---|
--json | Print the schema as JSON: every field with its rules, plus the live catalog parts. |
rfq template
stoa rfq template [OPTIONS]
Print a commented TOML request file to fill in, generated from the request schema.
| Option | Description |
|---|---|
--direction [BUY|SELL] | BUY = you are buying hardware; SELL = you are listing hardware. Required. |
--asset-type [bare|node|rack] | bare = loose GPUs, node = GPU servers, rack = a named rack system. Default node. |
whoami
stoa whoami [OPTIONS]
Show the signed-in user, organisation, and whether the marketplace accepts requests.
| Option | Description |
|---|---|
--json | Print the identity as JSON. |
Exit codes
| Code | Meaning |
|---|---|
0 | The command completed. |
1 | The venue refused the request; the message says why and carries a request id. |
2 | Usage error: a bad flag, a request file that fails validation, or a terminal needed and absent. |
3 | Sign in required. |
4 | Network problem. |
5 | This client is too old for the venue. Upgrade with uv tool install stoa-cli@latest (or pipx install --force stoa-cli). |
6 | No keychain is available to hold the session; the message says what to set up. |
A real create run with nobody at a terminal (--no-input, a pipe, a captured stderr) answers exit code 2 with the error code AGREEMENT_REQUIRED: the create records a person's agreement, so the person runs it in their own terminal.
JSON errors
Under --json a failure prints one JSON object on stdout as well as the message on stderr, so a script reads a document either way:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Notes cannot include contact details. Keep communication on Stoa.",
"status": 400,
"request_id": "…",
"exit_code": 1,
"idempotency_key": "…",
"rerun": "Re-run: stoa rfq create -f request.toml --idempotency-key …"
}
}
code is the venue's error code, or one of the client's own: USAGE, AGREEMENT_REQUIRED, SIGN_IN_REQUIRED, NETWORK, UPGRADE_REQUIRED, KEYCHAIN, CANCELLED. fields lists the fields a venue refusal names. idempotency_key and rerun appear on a create that may have reached the venue; run the rerun command exactly as printed and the venue can never open a second request.
Request limits
A create refused for the request limit prints the venue's sentence and when to try again.
Environment variables
| Variable | Purpose |
|---|---|
STOA_ | 1 makes every prompt an exit code instead of a wait, the same as --no-input. For scripts and coding agents under a pseudo-terminal. |