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 scoped on the server to the operations above. A request outside that scope is refused with a 403 even if the token were copied out of the keychain. 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.
A Stoa Markets account whose organization has completed onboarding.
Command line access enabled for your organization by the Stoa desk. Contact [email protected] to request it; the login reports when it is off.
A second factor enrolled 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.

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 upgrade stoa-cli

pipx upgrade stoa-cli

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 the upgrade line above instead of sending a request the server would refuse.

Choosing the venue

Every command names the venue it talks to with --env prod, or with the environment variable STOA_ENV=prod. There is no default, so a command never reaches the wrong venue by accident. The only public venue is production at markets.stoaexchange.com; the client pins that address and never follows a redirect away from it.

export STOA_ENV=prod
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

Start with Login and sessions, then the Quickstart.