Command reference
Every stoa CLI command, option and exit code for Stoa Markets, generated from the client's own command tree.
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_NO_INPUT. |
--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_NO_INPUT | 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. |