Stoa CLI

stoa is the command line client for Stoa Markets. It opens requests for quote from a request file and reads the quotes dealers return, under the same account and rules as the web application.

What it does

Command	Purpose
`login`, `logout`, `whoami`	Sign in with your Stoa Markets account and manage the local session.
`categories`, `assets search`	Browse the hardware catalog the venue trades.
`rfq schema`, `rfq template`	See the fields a request accepts and print a request file to fill in.
`rfq create`	Validate a request file with a dry run, then open the request.
`rfq list`, `rfq get`	Read your organization's requests and every quote received on them.
`agent-guide`	Print the instructions a coding agent needs to work with the client.

Commands print a readable table by default. whoami, categories, assets search, rfq schema, rfq create, rfq list and rfq get take --json for structured output.

What it does not do

The client cannot accept a quote, cancel or amend a request, submit a quote, touch settlement, send messages, change organization settings, or upload documents. Accepting a quote creates a binding trade, so that step stays in the web application, where the full terms are in front of you. rfq get prints the link to the request each time.

The venue enforces this: the session stoa login receives is limited on the server to the operations above. The Security page has the detail.

Requirements

macOS, Linux, or Windows.
Python 3.12 or later. uv installs a suitable Python for you when none is present.
An operating system keychain: macOS Keychain, Windows Credential Manager, or a Secret Service provider on Linux such as GNOME Keyring. The client stores session tokens there and nowhere else. On a headless Linux box, in WSL or over SSH the keychain must be running and unlocked in your session; Login and sessions has the recipe for each.
An active Stoa Markets registration and a second factor on your account (an authenticator app or a text-message number, under Settings, Security in the web application). Every command, the catalog included, runs under your signed-in session.
To open a request, your organization's marketplace setup in the web application must be complete. stoa whoami says whether it is.

Install

With uv:

uv tool install stoa-cli

With pipx:

pipx install stoa-cli

Confirm the install:

stoa --version

The package on PyPI is stoa-cli; the command it installs is stoa. Release notes are on the changelog page.

Upgrade

uv tool install stoa-cli@latest

pipx install --force stoa-cli

These work whether or not the install was pinned to a version. The client checks the minimum version the venue supports at the start of each run. When the venue requires a newer client, the command stops with exit code 5 and the upgrade line above instead of sending a request the server would refuse.

The venue

The client talks only to markets.stoaexchange.com and never follows a redirect away from it.

stoa whoami

Exit codes

Scripts and agents can branch on the exit code without parsing text. The codes are listed in the Command reference.

Next steps

The first command you run signs you in. Login and sessions has the detail; then follow the Quickstart.