batteryos

Command-line access to the BatteryOS energy-storage analytics API: prices, revenue analytics, asset performance, dispatch calculations and the ERCOT interconnection queue.

pipx install batteryos
bos configure login --email you@work.com
bos analysis tbn --iso ercot --node HB_HOUSTON --from 2025-01-01

Signing in

bos configure login emails a six-digit code and exchanges it for a token — three steps, one email, without leaving the terminal.

The CLI does not create accounts. If you have never signed in, do that once on the web first; login will otherwise tell you the address is unknown.

Credentials live in ~/.bos/credentials (mode 0600) and settings in ~/.bos/config, laid out like the AWS CLI's:

# ~/.bos/config
[default]
endpoint_url = https://batteryos.com/api/v1
output = table

[profile staging]
output = json

Select one with --profile staging, or BOS_PROFILE=staging. Resolution order is flag, then environment, then the named profile, then [default]. The flag works on either side of the command, as the AWS CLI's does — bos --profile staging queue pois and bos queue pois --profile staging are the same call.

Commands

bos configure   login logout whoami usage show profiles set
bos prices      actuals forwards status exchanges contracts contract compare
bos analysis    tbn rpo eon basis aggregate crr nodes eoncyc500 status
bos assets      list show timeline owners qse
                revenue revenue-perfect revenue-perfect-eo performance
                volume volume-perfect volume-perfect-eo volume-dispatch
                index percentiles ranking availability hsl cycles soc
bos calc        list data show status summary nodes scenarios ns result params create
bos queue       projects milestones project pois buses bus poi-buses

Any command or subcommand takes --help. A command with no subcommand prints its own help and exits 0. For a task-oriented tour of all six nodes with worked examples, see the CLI guide at batteryos.com/docs.

tbn, rpo, eon and aggregate read settled data by default and the forward curve under --futures. basis is settled-only.

Output

--output table|json|csv|ndjson. The default follows the terminal: a table when interactive, JSON when piped, so bos … | jq needs no flag.

Through 0.x the JSON shape is best-effort and may change within a minor release. It becomes a semver-governed contract at 1.0. Pin an exact version if you script against it before then.

Exit codes

A missing required argument exits 0 on purpose: not finishing a question is not the same as a command that ran and failed, and scripts need to tell them apart.

Long-running work

bos analysis eoncyc500 and bos calc create --apply start work that outlives the request, so they return a handle and exit. Add --wait to poll instead. A --wait that times out does not cancel anything — the message tells you how to resume polling.

Archives

bos prices forwards and bos calc result answer with a zip of CSVs. Both render it as series by default; --out also keeps the file, choosing the name and .zip suffix if you do not give one.

Changing things

bos calc create plans by default and prints what it would submit; add --apply to submit. --dry-run and --apply cannot be combined.

Environment