PuGa/docs/usage.md

Usage reference

Every tool runs as puga <tool> [args] (or tools/<tool>.py). puga help lists them, puga <tool> --help shows the options. CLAUDE.md has the authoritative one-paragraph description of each tool and its caveats; this page is the human-facing index.

Tools

Market

• price TICKER bid, ask, 7/30-day VWAP, volume, supply and demand at every exchange; fill price for a quantity.
• book TICKER order-book ladder with cumulative depth.
• sell TICKER QTY [--tight] [--tiers] where to post an ask, expected time to clear, a tranche split, and whether pricing above market is ever worth the wait.
• parkcash where to park idle cash in a buy-low/sell-high position while it has no better use.
• undervalued manufactured goods priced below their input cost (buy-and-hold candidates, low return).

Finding what to build

• scan ranks every recipe with a depth-aware market model: buildings the market can absorb, payback at realistic fill prices, staffed and understaffed variants, freight, planet-specific extraction and COGC (--planet).
• persistence rows.json re-prices scan rows over 30/90/180 days of history: is the margin a spike?
• history TICKER monthly margin history of one recipe.
• chain TICKER make-vs-buy cost tree; --consumers lists what eats the ticker downstream.
• planet RESOURCE --from PLANET ranks planets for a resource by extraction factor, founding cost and jump distance.
• route A B jump route between planets or systems.

Your own position

• state sync|show refreshes empire/state/company.yaml from FIO: cash, permits, buildings, efficiency, storage, ships.
• simulate spec.yaml | --uuid U replica of the PRUNplanner simulator; reports the real new capex (planned minus built).
• whatif base.yaml --add CHP:1 marginal payback of adding to a base you already run; flags newly overloaded workforce tiers and charges marginal freight.
• buy base.yaml --days N shopping list: construction gap plus N days of net operating stock, checked against cash.
• runway base.yaml days per material before the base stalls, including ships already inbound.
• network chain.yaml multi-base chain: mine here, ship, process there, with real freight.
• plan list | pull UUID | spec.yaml [--apply] | delete UUID read and write plans in your PRUNplanner account. Dry run by default; only [PuGa]-named plans are ever written.

Ships

• shiptrip SHIP FROM TO fuel cost of a trip for one of your ships.
• shipcost --jumps N ... the same from explicit physics parameters (gateway routes).
• lmscan PLANET live Local Market hauling ads ranked by margin after fuel.

Legacy

• prun_scan, prun_cxarb top-of-book scans kept as a baseline; they overstate thin markets.

Examples

puga state sync
puga price BHP --cx AI1
puga scan --cogc METALLURGY --experts METALLURGY=2 --min-n 3 --top 20
puga scan --planet ZV-307d --min-n 3
puga scan --min-n 3 --json rows.json && puga persistence rows.json
puga chain KV --qty 13
puga simulate plans/examples/hwp_buildout.yaml --basis vwap30
puga whatif my_base.yaml --add CHP:1
puga buy my_base.yaml --days 1.5
puga runway my_base.yaml
puga planet FEO --min-factor 0.5 --from ZV-759c

puga plan list
puga plan pull <uuid> -o my_plan.yaml
puga plan my_plan.yaml            # dry run
puga plan my_plan.yaml --apply
puga simulate --uuid <uuid>

Setup

Requires Python 3.12 or newer and git.

git clone <repo-url> PuGa && cd PuGa
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
source .venv/bin/activate         # once per shell, so `puga` is on your PATH
cp .env.example .env && chmod 600 .env && $EDITOR .env
tools/refresh_refs.sh             # optional: PRUNplanner source as mechanics reference (gitignored)
puga test
puga price BHP --cx AI1

.env

Gitignored, never committed. Do not paste keys into chat; edit the file.

Variable	What it is
FIO_USERNAME	your in-game / FIO user name
FIO_REST_KEY	FIO REST key (your sites, storage, production, ships, cash on rest.fnar.net)
FIO_API_KEY	FIO API (web) key; separate from the REST key, currently unused
PRUNPLANNER_API_KEY	API key from your PRUNplanner account, sent as Authorization: Api-Key <key>
COMPANY_CODE	your company code, used by the first state sync
DEFAULT_CX, DEFAULT_REGION	default exchange (AI1 = Antares) and region

Public data (prices, recipes, planets) works without keys. Your own data needs the FIO browser extension to have uploaded recently; run puga state sync and check as_of.

Layout

CLAUDE.md        entry point for Claude: rules, tool index, source-of-truth order
docs/            game and toolkit knowledge: mechanics, market model, decisions, roadmap, this file
puga/            library: data clients, market, economics, saturation, simulator, shipping
tools/           command line tools
plans/examples/  generic plan specs (also test fixtures)
state/           company.example.yaml, the shape of your synced state
tests/           pytest suite
empire/          (gitignored) YOUR empire: PROFILE.md, state/company.yaml, plans/, docs/
data/            (gitignored) fetched data cache
ref/             (gitignored) PRUNplanner source, read-only reference

Game knowledge and generic methods go in docs/; anything about your own bases, cash, decisions or preferences goes in empire/. puga state sync creates empire/state/company.yaml (set COMPANY_CODE in .env first). Add empire/PROFILE.md yourself: who you are, how you want answers, agreements with Claude.