6.5 KiB
CLI Reference
Most users should use the wrapper:
./scripts/ratchet setup
./scripts/ratchet
./scripts/ratchet defaults to ./scripts/ratchet next, the operator cockpit. It tells you exactly what to do next.
Use ./scripts/ratchet raw-cycle only when debugging the machine-readable cycle output.
Use ./scripts/ratchet app to build and open the packaged native macOS app. It creates macos/build/Braiins Ratchet.app; swift run is only a developer fallback.
Use ./scripts/ratchet guide for the user-facing operating story.
Use ./scripts/ratchet operator-guide for architecture, installation, migration, backup, recovery, and diagnostics.
Use ./scripts/ratchet mirror to print the native app's latest self-written visual-state snapshot from data/app_visual_state.md.
The raw Python CLI is documented below for debugging and development.
All raw commands should be run from the repository root.
Use the local virtual environment:
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli <command>
next
Prints the cockpit: current state, exact next operator action, interpretation, and reference commands.
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli next
Wrapper Guide Commands
These are wrapper commands, not raw Python subcommands:
./scripts/ratchet guide
./scripts/ratchet user-guide
./scripts/ratchet explain
./scripts/ratchet operator-guide
guide, user-guide, and explain print docs/USER_GUIDE.md.
operator-guide prints docs/OPERATOR_GUIDE.md.
Wrapper Reality Mirror Command
This is a wrapper command, not a raw Python subcommand:
./scripts/ratchet mirror
It prints data/app_visual_state.md, which is written by the SwiftUI app whenever it refreshes state or changes visible sections. If no snapshot exists yet, open the app with ./scripts/ratchet app and refresh or open Reality Mirror.
pipeline
Prints a monitor-only automation proposal and asks for yes or no.
Example behavior during post-watch cooldown:
I am going to: Wait for post-watch cooldown, then refresh once.
Are you OK with this? Type yes or no.
If approved, it waits until the earliest next action time, runs one fresh monitor cycle, prints the cockpit, and stops.
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli pipeline
supervise
Runs the durable forever lifecycle supervisor.
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli supervise
Status only:
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli supervise --status
Crash/reboot contract: start ./scripts/ratchet supervise again and it resumes from persisted SQLite lifecycle state.
position
Records manually executed Braiins exposure so the lifecycle supervisor can hold state across days/weeks.
Open a manual position:
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli position open --description "Braiins order abc" --maturity-hours 72
List positions:
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli position list
Close a finished position:
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli position close 1
init-db
Creates data/ratchet.sqlite if it does not exist.
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli init-db
collect-ocean
Fetches one OCEAN dashboard snapshot and stores:
- pool hashrate
- network difficulty
- share-log window
- estimated OCEAN block time
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli collect-ocean
collect-braiins-public
Fetches one token-free Braiins public market snapshot and stores:
- best bid
- best ask
- last average price
- market status
- total hashrate
- available hashrate
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli collect-braiins-public
Override the public base URL only for testing:
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli collect-braiins-public --base-url https://hashpower.braiins.com/webapi
cycle
Runs one complete monitor pass:
- collect OCEAN
- collect public Braiins market data
- evaluate the strategy
- store the resulting proposal
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli cycle
Use existing stored data for one side if needed:
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli cycle --skip-ocean
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli cycle --skip-braiins
watch
Runs a bounded monitor loop. The interval floor is 30 seconds to avoid hammering public endpoints.
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli watch --cycles 12 --interval-seconds 300
On normal completion, this writes a run report under reports/ and appends reports/EXPERIMENT_LOG.md.
experiments
Prints the master ratchet ledger.
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli experiments
retro-report
Summarizes already stored snapshots from an earlier run. Use --write to create a report file and append the ledger.
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli retro-report --since 2026-04-25T19:08:00+00:00 --until 2026-04-25T21:05:00+00:00 --run-id retro-second-watch --write
import-market
Imports a manual market JSON snapshot. Use this when public Braiins endpoints are unavailable.
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli import-market examples/market_snapshot.example.json
evaluate
Evaluates the latest stored OCEAN and Braiins snapshots against config.example.toml.
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli evaluate
The command returns observe, manual_canary, or manual_bid. It never places an order.
report
Prints the latest OCEAN snapshot, latest Braiins snapshot, sampled price range, and latest proposal. The sampled price range uses public Braiins snapshots only, so manually imported examples do not skew operational statistics.
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli report
Control the number of recent market samples used for min/avg/max:
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli report --samples 200
guardrails
Prints the active guardrails.
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli guardrails
Tests
Run all tests:
PYTHONPATH=src ./.venv/bin/python -m unittest discover -s tests
The test suite is network-free. Live collectors are validated separately by explicitly running their commands.