feat(cli): add litellm-token-count subcommand for offline token counting (Fixes #34772)

[Harsh23Kashyap]

TLDR

Problem this solves:

• Operators have no offline way to count tokens for a prompt from a shell
• litellm cost-estimate and litellm doctor already ship offline CLIs; token counting is the missing third
• The internal litellm.utils.token_counter() exists but requires a Python import to use

How it solves it:

• Adds a new litellm token-count subcommand that wraps litellm.token_counter()
• Supports --text, --file, and --messages (each with stdin via -) as mutually-exclusive inputs
• Outputs a one-line model=... mode=... count=N by default, or JSON via --json
• Privacy: input text and messages JSON never appear in stdout, only the count
• Mirrors the existing litellm-cost-estimate and litellm-doctor pattern in litellm/cli/

Relevant issues

• Fixes [Feature]: Add litellm token-count CLI subcommand for offline token counting #34772

Linear ticket

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Screenshots / Proof of Fix

Real CLI run against the local install (no proxy, no provider, no mock); commit 2fec98dfdd (HEAD of litellm_feat_token_count):

$ .venv/bin/python -m click.testing CliRunner on litellm.cli.token_count.cli \
    --model gpt-4o-mini --text "hello world"
model=gpt-4o-mini mode=text count=2

$ .venv/bin/python -c "from click.testing import CliRunner; from litellm.cli.token_count import cli; \
    r = CliRunner().invoke(cli, ['--model','gpt-4o-mini','--text','hello world','--json']); print(r.output.strip())"
{"model": "gpt-4o-mini", "mode": "text", "count": 2}

$ .venv/bin/python -c "from click.testing import CliRunner; from litellm.cli.token_count import cli; \
    r = CliRunner().invoke(cli, ['--model','gpt-4o-mini','--messages','[{\"role\":\"user\",\"content\":\"hi\"}]','--json']); print(r.output.strip())"
{"model": "gpt-4o-mini", "mode": "messages", "count": 8}

$ .venv/bin/python -c "from click.testing import CliRunner; from litellm.cli.token_count import cli; \
    r = CliRunner().invoke(cli, ['--model','gpt-4o-mini','--text','a','--file','/tmp/x']); print('exit:', r.exit_code, '|', r.output.strip())"
exit: 2 | Error: --text and --file are mutually exclusive; pass only one.

$ .venv/bin/python -m pytest tests/test_litellm/cli/test_token_count.py -v
tests/test_litellm/cli/test_token_count.py::test_count_tokens_with_text PASSED
... (23 tests total)
============================== 23 passed in 0.27s ==============================

Real count values are non-zero (2 for "hello world", 8 for a single user message with role+content overhead), so a regression that silently returns 0 would fail the tests.

Type

• New Feature

Changes

Two commits on litellm_feat_token_count (off litellm_internal_staging = 24123269cc):

• feat(cli): add litellm-token-count subcommand for offline token counting; adds litellm/cli/token_count.py (CLI + count_tokens() helper + TokenCount dataclass + TokenCountMessage TypedDict), the empty litellm/cli/__init__.py, and the litellm-token-count entry point in pyproject.toml.
• test(cli): cover litellm-token-count pass / fail / invalid-input paths; adds tests/test_litellm/cli/test_token_count.py with 23 tests across the programmatic helper and the CLI surface (pass paths, JSON output, mutually-exclusive flags, missing model, missing file, invalid JSON, non-list messages, privacy: text/messages never echoed to stdout).

Files added: litellm/cli/__init__.py, litellm/cli/token_count.py, tests/test_litellm/cli/test_token_count.py. Files modified: pyproject.toml (one line; new [project.scripts] entry mirroring litellm-cost-estimate and litellm-doctor).

No existing public Python API changes; litellm.utils.token_counter() keeps its current signature. The new count_tokens helper is a thin wrapper that calls the existing function with sensible defaults.

QA runbook

Not a proxy change, so no live-proxy QA needed. The CLI is exercised end-to-end via the CliRunner tests in tests/test_litellm/cli/test_token_count.py (23 tests, all passing locally). To verify locally:

.venv/bin/python -m pytest tests/test_litellm/cli/test_token_count.py -v

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[codecov]

Codecov Report

❌ Patch coverage is 89.41176% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/cli/token_count.py	89.41%	9 Missing ⚠️

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing Harsh23Kashyap:litellm_feat_token_count (66d0e79) with litellm_internal_staging (2412326)}