Metadata-Version: 2.4
Name: batteryos
Version: 0.1.0
Summary: Command-line interface for the BatteryOS energy-storage analytics API
Author: Financial Machines
License: Copyright (c) 2026 BatteryOS. All rights reserved.
        
        This software is distributed as a client for the BatteryOS API. Use of the
        API is governed by your BatteryOS subscription agreement.
        
Project-URL: Homepage, https://batteryos.com/
Project-URL: Documentation, https://batteryos.com/docs/
Keywords: bess,energy-storage,ercot,analytics,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: pretty
Requires-Dist: rich>=13; extra == "pretty"
Dynamic: license-file

# batteryos

Command-line access to the [BatteryOS](https://batteryos.com/) energy-storage
analytics API: prices, revenue analytics, asset performance, dispatch
calculations and the ERCOT interconnection queue.

```bash
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:

```ini
# ~/.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](https://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

| Code | Meaning |
|-----:|---------|
| 0 | success — also `--help`, a bare command, and a missing required argument |
| 1 | the request ran and failed (5xx, timeout, connection error) |
| 2 | usage error — an unknown flag or an invalid value |
| 3 | not signed in, or the credential was rejected |
| 4 | refused — not on your tier, or out of allowance |
| 5 | not found |
| 141 | a reader closed the pipe first — the command itself was fine |

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

| Variable | Effect |
|---|---|
| `BOS_PROFILE` | profile to use |
| `BOS_API_TOKEN` | bearer token, bypassing stored credentials |
| `BOS_ENDPOINT_URL` | API base URL |
| `BOS_OUTPUT` | default output format |
| `BOS_CONFIG_HOME` | directory holding `config` and `credentials` |
