@tallyify/cli (tally)

The command-line companion for Tallyify.

Browse and compare AI model pricing, estimate costs, watch for price changes, check provider status, export the pricing catalog, and record or read your usage telemetry — all without leaving your terminal.

• 🪶 Zero runtime dependencies — uses the native fetch in Node 18+.
• 🆓 Catalog commands need no account (search, list, show, cheapest, compare, calc, status, watch).
• 🔑 Data & telemetry commands (pull, track, watchlist, usage) use a Tallyify API key.
• 🤖 Scriptable — add --json to most commands for machine-readable output.

Table of contents

• Install
• Quick start
• Authentication & configuration
• Commands
• Global options
• JSON output & scripting
• Exit codes
• How it maps to the Tallyify API
• License

Install

npm install -g @tallyify/cli
tally --help

Or run it without a global install:

npx @tallyify/cli search "gpt-4o"

Requires Node 18+. The installed binary is tally.

Quick start

tally search "gpt-4o"                                     # search the catalog
tally show claude-3-5-sonnet                              # details + price-history sparkline
tally compare gpt-4o claude-3-5-sonnet gemini-2-5-flash  # side-by-side comparison
tally cheapest --category LLM --limit 5                  # cheapest priced models
tally calc --model gpt-4o --input 1500 --output 800 --requests 1000
tally status                                             # provider status + 90-day uptime

Catalog commands work with no account. pull, track, watchlist, and usage need an API key.

Authentication & configuration

Create an API key in your Tallyify profile → API Keys, then:

tally login --key tly_live_xxxxxxxx        # save the key
tally login --url http://localhost:3000    # (optional) point at another base URL
tally whoami                               # show base URL + masked key + source
tally logout                               # remove stored credentials

Where credentials live

Stored in ~/.tallyify/config.json with mode 600.

Precedence (high → low)

1. Environment variables
2. ~/.tallyify/config.json
3. Default base URL (https://api.tallyify.com)

Environment variables

| Variable | Use | | --- | --- | | TALLYIFY_API_KEY | API key — ideal in CI; takes precedence over the config file. | | TALLYIFY_BASE_URL | API base URL. | | AI_TRACKER_API_KEY / AI_TRACKER_BASE_URL | Legacy pre-rebrand aliases, kept as a fallback. |

In CI, set the environment variables and skip login entirely.

Required key scopes

| Command | Scope | Plan | | --- | --- | --- | | pull | pricing:read | Enterprise | | track | track:write | any | | watchlist (read) | watchlist:read | any | | watchlist toggle | watchlist:write | any | | usage | usage:read | any |

Commands

Catalog (no auth)

search <query>

Search models by name/provider. Flags: --provider, --category, --limit (default 25), --json.

tally search "gpt-4o" --provider OpenAI --limit 10

list

List models with filters. Flags: --provider, --category, --sort (name_asc|name_desc|price_asc|price_desc), --pricing (Free|Paid), --limit, --json.

show <slug>

Model details: pricing, specs, and a price-history sparkline. Flags: --json.

tally show claude-3-5-sonnet

cheapest

Cheapest paid models by input price (pricing=Paid, sort=price_asc). Flags: --category, --provider, --limit (default 10), --json.

compare <slug…>

Side-by-side comparison of 2+ models (feature × model table). Resolves each slug resiliently: an unknown slug is reported without sinking the whole comparison (needs ≥2 resolvable models). Flags: --json.

tally compare gpt-4o claude-3-5-sonnet

Cost (no auth)

calc

Estimate cost for a workload using the platform's pricing. Flags: --model <slug> (required), --input <tokens>, --output <tokens>, --requests <n> (default 1), --json.

tally calc --model gpt-4o --input 1500 --output 800 --requests 1000

The calculation applies the model's pricing unit divisor (1M / 1k / each), consistent with the platform's pricing logic.

Monitor (no auth)

status [provider]

Provider API status and 90-day uptime, with a colored indicator dot (none/minor/major/critical/maintenance/unknown). Optional provider slug/name filter. Flags: --json.

watch <slug…>

Poll one or more models and print a line whenever the price changes. Runs until interrupted (Ctrl-C), or once with --once. Flags: --interval <seconds> (default 60, min 5), --once.

tally watch gpt-4o claude-3-5-sonnet --interval 300

Data & telemetry (API key required)

pull

Export the pricing data feed (Enterprise feature, pricing:read scope). Flags: --provider, --category, --history (include history), --format json|csv (default json), --out <file> (otherwise stdout).

tally pull --format csv --out catalog.csv --history

track

Send a usage/cost event (track:write scope). Flags: --provider (required), --model, --input <tokens>, --output <tokens>, --endpoint, --status success|error (default success).

tally track --provider openai --model gpt-4o --input 1200 --output 350

watchlist

• tally watchlist — list your watchlist (watchlist:read).
• tally watchlist toggle <model_id> (aliases add/remove) — add/remove a model by id (watchlist:write). Flags: --json.

usage

Token & cost analytics for your account (usage:read). Flags: --period 7d|30d|90d, --provider <p>, --json.

tally usage --period 30d --provider OpenAI

Account

| Command | Description | | --- | --- | | login | Store credentials: --key <tly_live_…> and/or --url <https://…>. | | logout | Remove stored credentials. | | whoami | Show base URL, masked key, and source (env vs file). |

Global options

| Flag | Alias | Description | | --- | --- | --- | | --json | | Machine-readable JSON output. | | --limit <n> | -l | Max rows. | | --provider <p> | -p | Provider filter. | | --category <c> | -c | Category filter. | | --model <slug> | -m | Model (for calc). | | --out <file> | -o | Output file (for pull). | | --key <…> | -k | API key (for login). | | --url <…> | -u | Base URL (for login). | | -h, --help | | Show help. | | -v, --version | | Show version. |

The parser supports --flag value, --flag=value, boolean flags (--json, --history, --once, --help, --version), and short aliases -x value.

JSON output & scripting

Add --json to most commands for structured output — perfect for piping to jq:

# The three cheapest LLMs as JSON
tally cheapest --category LLM --limit 3 --json | jq '.[].slug'

# Export the full catalog to CSV (Enterprise data feed)
tally login --key tly_live_xxx
tally pull --format csv --out catalog.csv --history

# Record a usage event from a script
tally track --provider openai --model gpt-4o --input 1200 --output 350

# Your watchlist and this month's spend
tally watchlist --json
tally usage --period 30d --json | jq '.summary.monthly_spend'

Exit codes

• 0 — success.
• 1 — error (missing arguments, API error, unknown command).
• API errors print the server message; on 401/403 the CLI suggests tally whoami / tally login. Network errors print a "Could not reach the Tallyify API" message.

How it maps to the Tallyify API

In production, api.tallyify.com/<path> is proxied to the app's /api/<path>.

| Command | Method & path | Auth | | --- | --- | --- | | search / list / cheapest | GET /models | — | | show / calc / compare / watch | GET /models/{slug} | — | | status | GET /status | — | | pull | GET /v1/feed | Bearer (pricing:read, Enterprise) | | track | POST /v1/track | Bearer (track:write) | | watchlist | GET / POST /watchlist | Bearer (watchlist:read / watchlist:write) | | usage | GET /profile/api-keys/usage | Bearer (usage:read) |

To record usage telemetry directly from your application code (instead of shelling out to tally track), use the companion @tallyify/sdk.

License

ISC. See LICENSE.

Built for Tallyify — track, compare, and analyze AI model pricing and usage.