README.md

July 20, 2026 · View on GitHub

Cloudcash

Check your cloud spending from the CLI, from Waybar, and from the macOS menu bar!

Build

go build .

Configuration

Only add the services that you want to use and delete all the others:

cat ~/.config/cloudcash.toml

[Waybar]
Pango = "  {{.Name}} <span color='#aaaaaa'>${{.Status.CurrentCharges}}</span> [<span color='#aaaaaa'>${{.Status.PreviousCharges}}</span>]"
PangoJoiner = " · "

[Menu]
Template = "{{.Name}} ${{.Status.CurrentCharges}}"
Joiner = " · "
IsDefault = false

[Service]

[Service.Vultr]
APIKey = "XXXX"

[Service.DigitalOcean]
APIKey = "XXXX"

[Service.AWS]
AWSAccessKeyID = "AAAA"
AWSSecretAccessKey = "XXXX"
Region = "us-east-1"

[Service.GitHub]
APIKey = "XXXX"
Users = [
  "mrusme"
]
Orgs = [ 
  "paper-street-soap-co"
]

[Service.Claude]
Enabled = true

[Service.Codex]
Enabled = true

Alternative paths for configuration file:

/etc/cloudcash.toml
$XDG_CONFIG_HOME/cloudcash.toml
$HOME/.config/cloudcash.toml
$HOME/cloudcash.toml
./cloudcash.toml

Note regarding GitHub: You can specify multiple users/orgs, which are queried and added up to one total amount. Calculation is done locally, based on the paid minutes reported by the GitHub API and the officially available numbers, and could be off to a certain degree, due to additional costs that might have incurred on GitHub.

Note regarding Claude: This reports your Claude subscription (Pro/Max) usage, not Claude API billing. Alongside the usage credits spent so far, it exposes two extra fields that no other service provides: {{.Status.SessionUsage}} (current 5-hour session) and {{.Status.WeeklyUsage}} (current 7-day window), both as percentages of your plan's quota.

By default the OAuth token is read from ~/.claude/.credentials.json, which the Claude Code CLI maintains and refreshes. Override the location with CredentialsFile, or pass a token directly with OAuthToken:

[Service.Claude]
Enabled = true
# CredentialsFile = "/home/you/.claude/.credentials.json"
# OAuthToken = "XXXX"

Be aware that Anthropic offers no documented API for subscription usage. This uses the same undocumented endpoint that Claude Code's own /usage command queries, so it may break without notice. Anthropic's documented usage and cost APIs cover API organizations only, require an Admin API key, and are not available to individual accounts.

Note regarding Codex: This reports your ChatGPT subscription usage, not OpenAI API billing, and works the same way the Claude provider does. It fills {{.Status.SessionUsage}} from the 5-hour window and {{.Status.WeeklyUsage}} from the weekly one. OpenAI reports credits remaining rather than credits spent, so the figure ends up in {{.Status.AccountBalance}} and CurrentCharges stays at zero. Accounts on an unlimited plan report no balance.

The OAuth token and account ID are read from $CODEX_HOME/auth.json, falling back to ~/.codex/auth.json, which the Codex CLI maintains and refreshes:

[Service.Codex]
Enabled = true
# CredentialsFile = "/home/you/.codex/auth.json"
# OAuthToken = "XXXX"
# AccountID = "XXXX"

The same caveat as with Claude applies, only more so: OpenAI publishes no API for subscription usage, and this queries the endpoint the Codex CLI polls for its /status output. Newer Codex versions can keep credentials in the system keyring instead of auth.json, in which case there is no token to read and you have to set OAuthToken yourself. OpenAI's documented costs and usage APIs cover platform spending only and need an admin key.

Waybar

The Pango template used in the -waybar-pango output is used per service, separated by the PangoJouner string. To make it clear, if Pango is <span>{{.Name}}</span> and PangoJoiner is - then the output for two services (e.g. Vultr and AWS) would be:

<span>Vultr</span> - <span>AWS</span>

The Pango configuration uses Go's text/template.

PangoUsage is a second template, appended to Pango, that renders only for services reporting quota usage, currently Claude. Pango applies to every service, so putting {{.Status.SessionUsage}} in it would show 0% next to Vultr, AWS and everyone else. It defaults to:

PangoUsage = " [<span color='#aaaaaa'>{{.Status.SessionUsage}}%</span> · <span color='#aaaaaa'>{{.Status.WeeklyUsage}}%</span>]"

Set it to "" to leave the percentages out of the Waybar output.

The Template in Menu is what is used to render the macOS menu bar widget. As with the Waybar output, the template is per service, separated by the Joiner string. Unlike the Waybar.Pango configuration, Menu.Template does not support Pango, but it can include things like Emojis.

To always run in menu mode, set Menu.IsDefault to true.

Use

CLI (text)

cloudcash

CLI (JSON)

cloudcash -json

Waybar

rg -NA6 'cloudcash":'  ~/.config/waybar/config

"custom/cloudcash": {
  "format": "{}",
  "return-type": "json",
  "exec": "/usr/local/bin/cloudcash -waybar-pango",
  "on-click": "",
  "interval": 3600
},

cloudcash -menu-mode

Alternatively set Menu.IsDefault to true in configuration.