Set a budget and put usage in your prompt

Reports are for sitting down with. These two commands are for the rest of the time, when you want the number in the corner of your eye rather than on the screen.

A budget you can check

tokenstat budget sets a soft cap and tells you where you stand against it:

tokenstat budget --daily 20
tokenstat budget --monthly 300
tokenstat budget

The last one prints today's and this month's totals, each as a percentage of its cap, marked ok or over. With no cap set it says so and shows you the flag that would set one. --daily 0 or --monthly 0 clears that cap, and --clear removes both.

Two things this is not:

It is not billed dollars. The figure is list-rate equivalent, the same measure used everywhere else in tokenstat. Work covered by a subscription still shows a list value, because the point is the scale of what you did, not what anyone charged you. Why cache reads dominate your token count has the longer version of that distinction.

It is not enforcement. Nothing stops a request at the cap. tokenstat reads logs after the fact and has no position between you and a vendor. A budget here is a number to notice, not a switch.

Budget needs prices, so run tokenstat pricing --refresh first if you have not. Without a price book it will tell you the money column has nothing to work from.

Add --json if you want the same status inside a script:

tokenstat budget --json

A line for your prompt

tokenstat statusline prints exactly one line and exits:

tokenstat statusline

By default that is {today} today · {month} this month. The format is yours:

tokenstat statusline --format '{today_value} today · {month_value} mtd'

It was written to be safe on a prompt, which drove three decisions worth knowing about:

• It never scans. It reads the archive and nothing else, so it cannot block on a slow filesystem walk or a network call.
• It fails silently. No data, no archive, no prices: it prints nothing rather than an error. A status line that breaks your shell prompt is worse than no status line.
• Staleness is handled in the background. If the archive is older than --max-age seconds (900 by default), it appends the {stale} marker and kicks off a scan behind a lock. The line you are looking at still returns immediately. Pass --max-age 0 to turn the check off.

{today_in_out} deserves a note. It counts fresh input and output only, leaving cache reads out. On a normal machine cache reads are the large majority of every token, so a raw total on a prompt is a number that barely moves. Input plus output tracks the work you actually asked for.

Related

• Which tokenstat command shows what is the map of the full report set.
• Why cache reads dominate your token count explains why the money column and the token column tell different stories.