Usage CLI reference
Read what your turns cost: today, the range, a row per day, and a row per model.
Use this page to read what atoi usage answers and the flags it takes. The numbers come from the model-decision receipts a turn writes, so the terminal, the atoi_usage tool, and the Usage section of Billing all answer from one place.
atoi usageRead what the turns cost, from the model-decision receipts: today, the window, by day, and by model.
#usage get
Read what your turns cost in the Workspace the terminal is standing in: today, the window, a row per day, and a row per model.
atoi usage [get] [--days <n> | --from <time> --to <time>] [--workspace <workspace-id>] [--personal]
| Flag | Type | Default | Values | What it does |
|---|---|---|---|---|
--days | number | Read this many days back, ending now. Seven when omitted. | ||
--from | string | Read from this time, as an ISO time or a millisecond timestamp. Use it with --to when you mean to compare two reads. | ||
--to | string | Read up to this time. Now when omitted. | ||
--workspace | string | Answer one Workspace by id for this call; without it, the Workspace the terminal is standing in. | ||
--personal | boolean | Answer Personal for this call, whatever the terminal is standing in. | ||
--json | boolean | false | Emit the canonical JSON envelope. | |
--ndjson | boolean | false | Emit one canonical JSON envelope per line. | |
--format | string | text | text, json | Choose human text or the JSON envelope. |
--help -h | boolean | Show command help. |
#Run usage get
atoi usage --days 7 --json{
"tool": "atoi_usage",
"arguments": {
"action": "get",
"days": 7
}
}Without --workspace, the read answers for the Workspace the terminal is standing in; --personal steps out to Personal for one call.
#Read a fixed range
--days reads a window that ends now, so two reads taken minutes apart cover different windows. When you mean to compare two reads, or to subtract one from another, ask for the range by its ends.
atoi usage --from 2026-09-14T00:00:00Z --to 2026-09-14T12:00:00Z --jsonThe answer names the range it read, so you can see that two reads covered the same one. A turn outside the range is never counted, and a turn inside it follows any later re-pricing. Pass --days or a range, not both.
Read Billing for the same numbers in the product, or the CLI reference index for every command.
Was this useful?