Petri command reference
This reference lists every public command of Petri’s mainnet build. Run petri help, or petri <command> --help, for the exact options of the build you have installed.
In the tables, Reads means the command reads the chain or the futures API and signs nothing. Signs means Petri shows what the command will do, asks (unless --yes), and signs with your wallet. Local commands need neither.
MARKET is a symbol (ramx: the open market of that index that expires first), a name (ramx-nov26) or an address. Market and trading commands also take --expiry <EXPIRY> to pick an expiry for a bare symbol: nov26, 2026-11 or unix seconds. OWNER is any wallet’s public address; it defaults to yours.
Global options
Section titled “Global options”Options can go before or after the command name.
| Option | Environment variable | Default | Meaning |
|---|---|---|---|
--profile <PROFILE> |
PETRI_PROFILE |
Saved profile, then production |
The deployment Petri talks to and trusts: production (Solana mainnet; also prod, mainnet) or dev (a local chain, for developers; also localnet). |
--rpc <URL> |
PETRI_RPC_URL |
Saved rpc, then the profile’s: https://api.mainnet-beta.solana.com |
Solana RPC: a full RPC node. The public default is rate-limited; heavy users should set their own. |
--api <URL> |
PETRI_API_URL |
Saved api, then the profile’s: https://api.amoeba.farm |
Amoeba’s futures API. |
--keypair <PATH> |
SOLANA_KEYPAIR |
Saved keypair, then the Solana CLI config, then ~/.config/solana/id.json |
The wallet that signs: a key file, or a hardware wallet such as usb://ledger. |
--route <ROUTE> |
auto |
Who pays the network fee: local (your wallet), sponsored (the futures API’s sponsor) or auto (local when your wallet has SOL for fees). |
|
--json |
AMEBA_OUTPUT=json |
off | Print JSON. |
--yes |
off | Send without asking for confirmation. | |
--no-color, --plain |
NO_COLOR |
off | No colors. |
--deployment <PATH> |
PETRI_DEPLOYMENT |
The futures API’s /v1/config |
Deployment manifest with the program addresses to trust. |
--solana-config <PATH> |
SOLANA_CONFIG |
~/.config/solana/cli/config.yml |
Solana CLI config to find the key file in. |
--allow-insecure-keypair |
AMEBA_ALLOW_INSECURE_KEYPAIR |
off | Allow signing with a key file other users can read. Not recommended. |
--version, --help |
Print the version or help. |
See Configuration and wallet safety for how these are resolved, and Use your own RPC for the RPC methods Petri needs.
Start and help
Section titled “Start and help”| Command | Purpose | Needs |
|---|---|---|
petri |
A short guide and whether a wallet is attached. | Local |
petri help [COMMAND] |
Every command, or one command’s options. | Local |
Markets
Section titled “Markets”| Command | Purpose | Needs |
|---|---|---|
markets |
Every futures market: price, 24-hour change, index, 24-hour volume, settlement date and status. | Reads |
markets <MARKET>, market <MARKET> |
One market: price, index, suggested range, best prices, activity and settlement. | Reads |
book <MARKET> [--range LO-HI] [--depth N] |
What one range costs to buy or sell, level by level. --range defaults to the suggested range, --depth to 10 levels a side. |
Reads |
trades <MARKET> [--limit N] |
Recent trades. 20 by default. | Reads |
chart <MARKET> [1h|24h|7d|30d|all] [--height N] |
Price chart. 24 hours and 14 rows by default. | Reads |
See Read commands.
Trading
Section titled “Trading”| Command | Purpose | Needs |
|---|---|---|
quote long|short <MARKET> [LOTS] |
Price an order exactly as long or short would send it. Takes the order options below. |
Reads |
long <MARKET> [LOTS] |
Buy a range. Alias: buy. |
Signs |
short <MARKET> [LOTS] |
Sell a range. Alias: sell. |
Signs |
close <MARKET> <#|all> [-n, --lots N] [--slippage PCT] [--keep-cash] |
Close a position at the book, or every position in that market. Sends the proceeds to your wallet unless --keep-cash. |
Signs |
cancel <MARKET> <#|all> |
Cancel a resting order, or every one in that market. | Signs |
deposit <MARKET> <USD> |
Move USDC from your wallet into a market. | Signs |
withdraw <MARKET> <USD|all> |
Move free cash from a market back to your wallet. | Signs |
Order options for quote, long and short:
| Option | Default | Meaning |
|---|---|---|
LOTS |
Lots to trade. A lot pays $0.01 per index point inside its range. | |
--usd <USD> |
Spend about this much USDC instead of naming lots. | |
-x, --leverage <X> |
10 | Sets the losing end of the range: entry minus entry ÷ X for a long, entry plus entry ÷ X for a short. |
--to <PRICE> |
The suggested range’s end | The winning end of the range. |
--range <LO-HI> |
Both ends, instead of -x and --to. |
|
--limit <PRICE> |
A limit order at this entry. What doesn’t fill now rests on the book. | |
--post |
With --limit: only rest, never fill now. |
|
--slippage <PCT> |
2 | Market orders: how much worse than the quote they may fill, in percent. |
Give either LOTS or --usd. Position and order numbers come from petri positions. See Trading and wallet actions and Settlement.
Account and wallet
Section titled “Account and wallet”| Command | Purpose | Needs |
|---|---|---|
positions [OWNER] |
Positions, resting orders and cash in each market, with P&L. Aliases: account, pos. |
Reads |
history [OWNER] [--limit N] |
Trades, orders, deposits, withdrawals and settlements. 50 rows by default. | Reads |
wallet [OWNER] |
Address, SOL, USDC and cash in each market. | Reads |
wallet address |
Your wallet’s public address. | Local |
wallet new [--out PATH] [--force] |
Create a signing wallet. Prints only its address. Without --out, it becomes the wallet Petri signs with. |
Local |
status |
Check the profile and cluster, the cluster’s clock, the futures API, the trusted programs, the markets and your wallet. | Reads |
Oracle reads
Section titled “Oracle reads”| Command | Purpose | Needs |
|---|---|---|
oracle, oracle months [MARKET] |
Oracle months: phase, sources and settlement status. MARKET is ramx, nandx or a month such as RAMX-202610. |
Reads |
oracle latest [MARKET] |
The most recently updated oracle month. | Reads |
oracle history [MARKET] |
Oracle months by last update, newest first. | Reads |
oracle catalog |
Every oracle period with its settlement time. | Reads |
oracle sources [MARKET] [--expiry M] [--query TEXT] [--limit N] |
A month’s source inventory. 40 rows per month by default. | Reads |
oracle recipe [MARKET] [--expiry M] [--query TEXT] [--limit N] |
A month’s buckets with their weights and sources. | Reads |
oracle candidates [--market M] [--expiry M] [--agent ID] [--limit N] |
Source candidates submitted by research agents. They carry no oracle weight. | Reads |
oracle candidates show <HASH> |
One candidate by its content hash. | Reads |
oracle collateral [--owner PUBKEY] |
USDC bond collateral in the oracle. | Reads |
oracle evidence show [OBJECT] [--kind K --text TEXT] [--payer PUBKEY] |
An evidence object, by address or by kind and text. | Reads |
Oracle writes
Section titled “Oracle writes”Every oracle write is reviewed and confirmed (or --yes), then signed by your wallet, which pays its fee. Add --simulate to run it without signing. Bonds and stakes come out of your oracle collateral. Run petri oracle <command> --help for every option.
| Command | Purpose |
|---|---|
oracle collateral deposit <USDC> |
Move USDC from your wallet into your oracle collateral. |
oracle collateral withdraw <USDC|all> |
Move available oracle collateral back to your wallet. |
oracle evidence write --kind locator|definition|archive (--text TEXT | --file PATH) |
Write and seal a public evidence object: a source URL, a source definition or a Wayback archive URL. |
oracle evidence close <OBJECT> |
Close an unsealed evidence draft and refund its rent. |
oracle sources propose <MARKET> --bucket SKU --url URL --source-type TEXT --bond USDC |
Propose a source with a listing bond. Writes its evidence first. Takes --definition or --definition-file. |
oracle sources support <MARKET> --source S --stake USDC |
Support a source with a stake. |
oracle sources challenge <MARKET> --source S --reason CODE --bond USDC --evidence-hash HEX |
Challenge a candidate source with a bond. |
oracle prints opening <MARKET> --source S --value V --archive-url URL --stake USDC |
Submit a bonded opening print with its Wayback archive. |
oracle prints challenge <MARKET> --source S --value V --archive-url URL --bond USDC |
Challenge an opening print with an alternative. |
oracle prints finalize <MARKET> --source S |
Accept an unchallenged opening print after its window. |
oracle prints expire <MARKET> --source S |
Mark an unclaimed frozen source inactive. |
oracle prints finalize-phase <MARKET> |
Close the opening phase: the month enters Game and its period goes live. |
oracle updates commit <MARKET> --source S --value V --archive-url URL --stake USDC |
Commit a sealed source update with a stake. The reveal data stays private. |
oracle updates reveal <CLAIM> |
Reveal a committed update with its Wayback archive. |
oracle updates challenge <MARKET> --claim C --value V --archive-url URL --bond USDC |
Challenge a revealed update with an alternative. |
oracle updates expire <MARKET> --claim C |
Refund a commitment nobody revealed, after its deadline. |
oracle stakes settle <MARKET> --kind KIND --source S |
Settle a finished bond or stake back into your oracle collateral. |
oracle emergency propose|vote|apply|recover <MARKET> --kind KIND --target T --target-id ID |
Council dispute cases: open a case, vote with your council seat, apply the decision or its fallback, apply a thin-bucket recovery. |
For oracle writes, MARKET is ramx, nandx, a month such as RAMX-202610, or a period address; --expiry takes oct26, 2026-10 or unix seconds. See Evidence rules and Challenges.
Setup and research
Section titled “Setup and research”| Command | Purpose | Needs |
|---|---|---|
config, config show |
The profile and cluster, and every setting and where it comes from. | Local |
config set <KEY> <VALUE> |
Save a setting. Keys: profile, rpc, api, keypair, deployment. |
Local |
config reset <KEY> |
Restore a setting to its default. | Local |
mcp status, enable, repair, disable |
Manage the AI agent connection. | Local |
mcp manifest |
Print the agent tool manifest. | Local |
update check, update info |
Check for a newer release; show this install’s version and update channel. | GitHub releases |
update [--yes] [--restart] |
Install the latest release after confirmation. | GitHub releases |
update recover [--restart] |
Restore the previous app files after an interrupted update. | Local |
tui [--no-update-check] |
Open the terminal interface: markets and the oracle research workspace. | Reads |
research ... |
Connect research agents and submit source candidates. petri research --help lists its commands. |
Research workspace |
See Connect an AI agent.
Environment variables
Section titled “Environment variables”| Variable | Effect |
|---|---|
PETRI_PROFILE |
The profile, as --profile. |
PETRI_RPC_URL, PETRI_API_URL |
The Solana RPC and futures API, as --rpc and --api. |
SOLANA_KEYPAIR, SOLANA_CONFIG |
The signing wallet, as --keypair and --solana-config. |
PETRI_DEPLOYMENT |
The deployment manifest, as --deployment. |
PETRI_CONFIG_PATH |
Use a different settings file. |
AMEBA_OUTPUT=json |
JSON output, as --json. |
AMEBA_ALLOW_INSECURE_KEYPAIR |
As --allow-insecure-keypair. |
NO_COLOR |
No colors. |
PETRI_UPDATE_CHECK=0 |
Turn off background update checks in the terminal interface. |
PETRI_MCP_NODE_BIN |
Node.js executable for petri mcp enable when node is not on PATH. |
Updating a source build
Section titled “Updating a source build”Packaged downloads update with petri update. A build compiled from source updates from Git instead: Petri installs fetched source only after you verify the full release commit and set PETRI_TRUSTED_UPDATE_COMMIT to that 40-character commit. petri update --no-fetch inspects local references without fetching.