Command Line Interface

The CLI module provides a command-line interface for toksum functionality.

Command-line interface for toksum.

This module provides a comprehensive command-line interface for the toksum library, allowing users to count tokens and estimate costs for various LLM models directly from the terminal.

The CLI supports:

  • Token counting for text input or files

  • Cost estimation with detailed breakdowns

  • Listing all supported models by provider

  • Verbose output with detailed information

  • Support for both input and output token pricing

Examples

Basic token counting:

toksum "Hello, world!" gpt-4
toksum --file input.txt claude-3-opus-20240229

Cost estimation:

toksum --cost "Your text here" gpt-4
toksum --cost --output-tokens "Response text" gpt-4

List supported models:

toksum --list-models

Verbose output:

toksum --verbose --cost --file large_document.txt gpt-4
Functions:

main: Main CLI entry point that handles argument parsing and execution list_models: Display all supported models organized by provider

The CLI provides comprehensive error handling and user-friendly output formatting for both simple token counting and detailed cost analysis workflows.

toksum.cli.main() → None[source]

Main CLI entry point.

Parses command-line arguments and executes the appropriate toksum functionality. Supports token counting, cost estimation, model listing, and file input processing.

The function handles:

  • Argument parsing and validation

  • Text input from command line or file

  • Token counting for specified models

  • Cost estimation with input/output token differentiation

  • Model listing with provider organization

  • Comprehensive error handling and user feedback

  • Verbose output formatting

Command-line Arguments:

text (str, optional): Text to count tokens for model (str, optional): Model name (required unless using –list-models) –file, -f (str): Read text from file instead of command line –list-models, -l: List all supported models by provider –cost, -c: Show cost estimation along with token count –output-tokens: Calculate cost for output tokens instead of input –verbose, -v: Show detailed output with additional information

Exit Codes:

0: Success 1: Error (unsupported model, file not found, tokenization failure, etc.)

Raises:

SystemExit – On error conditions or user interruption

Examples

Basic usage:

toksum "Hello, world!" gpt-4
toksum --file document.txt claude-3-opus-20240229

With cost estimation:

toksum --cost --verbose "Long text content" gpt-4
toksum --cost --output-tokens "Response text" gpt-4

List models:

toksum --list-models
toksum.cli.list_models() → None[source]

List all supported models organized by provider.

Displays a comprehensive list of all supported models grouped by their respective providers (OpenAI, Anthropic, Google, Meta, etc.). The output includes model counts per provider and a total count across all providers.

The function:

  • Retrieves all supported models using get_supported_models()

  • Groups models by provider with clear section headers

  • Sorts models alphabetically within each provider

  • Shows model counts for each provider and overall total

  • Formats output for easy readability

Output Format:
Supported models:
==================================================

OPENAI (25 models):
------------------------------
  gpt-3.5-turbo
  gpt-4
  gpt-4o
  ...

ANTHROPIC (12 models):
------------------------------
  claude-3-haiku-20240307
  claude-3-opus-20240229
  ...

Total: 200+ models

Note

This function is typically called when the –list-models CLI flag is used. It provides users with a complete overview of available models for token counting and cost estimation.

Functions

toksum.cli.main() → None[source]

Main CLI entry point.

Parses command-line arguments and executes the appropriate toksum functionality. Supports token counting, cost estimation, model listing, and file input processing.

The function handles:

  • Argument parsing and validation

  • Text input from command line or file

  • Token counting for specified models

  • Cost estimation with input/output token differentiation

  • Model listing with provider organization

  • Comprehensive error handling and user feedback

  • Verbose output formatting

Command-line Arguments:

text (str, optional): Text to count tokens for model (str, optional): Model name (required unless using –list-models) –file, -f (str): Read text from file instead of command line –list-models, -l: List all supported models by provider –cost, -c: Show cost estimation along with token count –output-tokens: Calculate cost for output tokens instead of input –verbose, -v: Show detailed output with additional information

Exit Codes:

0: Success 1: Error (unsupported model, file not found, tokenization failure, etc.)

Raises:

SystemExit – On error conditions or user interruption

Examples

Basic usage:

toksum "Hello, world!" gpt-4
toksum --file document.txt claude-3-opus-20240229

With cost estimation:

toksum --cost --verbose "Long text content" gpt-4
toksum --cost --output-tokens "Response text" gpt-4

List models:

toksum --list-models
toksum.cli.list_models() → None[source]

List all supported models organized by provider.

Displays a comprehensive list of all supported models grouped by their respective providers (OpenAI, Anthropic, Google, Meta, etc.). The output includes model counts per provider and a total count across all providers.

The function:

  • Retrieves all supported models using get_supported_models()

  • Groups models by provider with clear section headers

  • Sorts models alphabetically within each provider

  • Shows model counts for each provider and overall total

  • Formats output for easy readability

Output Format:
Supported models:
==================================================

OPENAI (25 models):
------------------------------
  gpt-3.5-turbo
  gpt-4
  gpt-4o
  ...

ANTHROPIC (12 models):
------------------------------
  claude-3-haiku-20240307
  claude-3-opus-20240229
  ...

Total: 200+ models

Note

This function is typically called when the –list-models CLI flag is used. It provides users with a complete overview of available models for token counting and cost estimation.

Usage Examples

Basic Token Counting

Count tokens for a simple text string:

toksum "Hello, world!" gpt-4

Count tokens from a file:

toksum --file document.txt claude-3-opus-20240229

Cost Estimation

Get cost estimates along with token counts:

toksum --cost "Your text here" gpt-4

Calculate output token costs:

toksum --cost --output-tokens "Response text" gpt-4

Model Discovery

List all supported models:

toksum --list-models

Verbose Output

Get detailed information:

toksum --verbose --cost --file large_document.txt gpt-4

Command Line Arguments

Positional Arguments

  • text - Text to count tokens for (optional if using –file)

  • model - Model name (required unless using –list-models)

Optional Arguments

  • --file, -f - Read text from file instead of command line

  • --list-models, -l - List all supported models

  • --cost, -c - Show cost estimation along with token count

  • --output-tokens - Calculate cost for output tokens instead of input

  • --verbose, -v - Show verbose output with additional details

Exit Codes

  • 0 - Success

  • 1 - Error (unsupported model, file not found, tokenization failure, etc.)