tokenpak

CLI Reference

Complete reference for all tokenpak commands.

Status & Health

tokenpak status

Check proxy health and session stats.

tokenpak status [--full]
Flag Description
--full Include compression pipeline details and recent request log

tokenpak health

Full system health check including DB, index, and proxy subsystems.

tokenpak health

tokenpak logs

View proxy logs.

tokenpak logs [--errors] [--today] [--tail N]
Flag Description
--errors Show only error-level entries
--today Filter to today’s logs
--tail N Show last N lines (default: 50)

tokenpak doctor

Comprehensive diagnostics — checks config, proxy, DB, compression pipeline, and connectivity.

tokenpak doctor

Proxy Server

tokenpak serve

Start the proxy server.

tokenpak serve [--port PORT] [--mode MODE] [--daemon]
Flag Default Description
--port 8766 Port to listen on
--mode hybrid Compression mode: strict, hybrid, aggressive
--daemon off Run in background

Compression modes:

Mode Behavior
strict Only compress if token count exceeds threshold
hybrid Compress medium+ requests, pass through small ones
aggressive Always compress

tokenpak stop

Stop the background proxy daemon.

tokenpak stop

Cost & Budget

tokenpak cost

View cost breakdown.

tokenpak cost [--today] [--week] [--month] [--by-model] [--by-agent] [--export FORMAT]
Flag Description
--today Today’s costs
--week This week
--month This month
--by-model Break down by model
--by-agent Break down by agent
--export csv\|json Export to file

tokenpak budget

Manage spending limits.

tokenpak budget set --monthly AMOUNT
tokenpak budget alert --at PCT
tokenpak budget status
tokenpak budget reset
Subcommand Description
set --monthly N Set monthly budget in USD
alert --at PCT Alert when budget reaches PCT% (e.g. 80%)
status Show current budget and spend
reset Clear budget and spend history

tokenpak savings

View cumulative token savings.

tokenpak savings [--lifetime] [--export csv]

Compression

tokenpak demo

Run the compression pipeline on a sample and show what was removed.

tokenpak demo [--verbose] [--file PATH]

tokenpak compress

Dry-run compression on a file (no request sent).

tokenpak compress <file> [--diff] [--mode MODE]
Flag Description
--diff Show a diff of what was removed
--mode Override compression mode

tokenpak trace

Inspect a pipeline execution trace.

tokenpak trace [--id ID] [--last]

Vault & Indexing

tokenpak index

Index a directory for semantic search.

tokenpak index [PATH] [--watch] [--status] [--auto-workers] [--max-workers N]
Flag Description
PATH Directory to index (default: current dir)
--watch Auto re-index when files change
--status Show index health without re-indexing
--auto-workers Use calibration profile to set parallelism
--max-workers N Cap at N parallel workers

Semantic search over the indexed vault.

tokenpak vault search "query" [--top N] [--type TYPE]
Flag Description
--top N Return top N results (default: 5)
--type Filter by block type: code, text, config

tokenpak vault blocks

Inspect indexed content blocks.

tokenpak vault blocks [--stale] [--type TYPE] [--path PATTERN]

Benchmarking & Calibration

tokenpak benchmark

Measure compression performance and token savings.

tokenpak benchmark PATH [--iterations N] [--compare]
Flag Description
--iterations N Runs per file (default: 3)
--compare Show baseline vs optimized comparison

tokenpak calibrate

Profile your hardware to find optimal worker count.

tokenpak calibrate PATH [--max-workers N] [--rounds N]
Flag Description
--max-workers N Maximum workers to test
--rounds N Test rounds per worker count (default: 2)

Saves profile to ~/.tokenpak/calibration.json.

Model Routing

tokenpak route

Manage request routing rules.

tokenpak route set PATTERN MODEL
tokenpak route test "prompt text"
tokenpak route list
tokenpak route history
tokenpak route remove PATTERN

Examples:

# Route test/debug queries to a cheaper model
tokenpak route set ".*test.*" gpt-4o-mini
tokenpak route set ".*debug.*" claude-haiku-3-5

# Preview what model a prompt would be routed to
tokenpak route test "write unit tests for auth.py"
# → gpt-4o-mini (matched: .*test.*)

Agent Management

tokenpak agent

Manage registered agents.

tokenpak agent list
tokenpak agent register NAME [--metadata KEY=VALUE]
tokenpak agent unregister NAME
tokenpak agent tasks [--queue] [--agent NAME]
tokenpak agent lock FILE [--ttl SECONDS]

Event Triggers

tokenpak trigger

Configure event-based automations.

tokenpak trigger list
tokenpak trigger add EVENT_TYPE CONDITION COMMAND
tokenpak trigger remove ID
tokenpak trigger log [--last N]

Event types:

Type Condition Example
file-change Glob pattern "*.py"
cost-alert Percentage 80%
model-change Model name "gpt-4o" 
tokenpak trigger add file-change "*.py" "bash lint.sh"
tokenpak trigger add cost-alert 80% "notify --urgent"

A/B Testing

tokenpak ab

Run controlled compression experiments.

tokenpak ab create NAME --variant-a DESC --variant-b DESC
tokenpak ab status NAME
tokenpak ab apply NAME
tokenpak ab presets
tokenpak ab list

Replay & Debug

tokenpak replay

Replay a past request (useful for testing recipe changes).

tokenpak replay list [--last N]
tokenpak replay ID [--no-compress] [--model MODEL] [--diff]
Flag Description
--no-compress Replay without compression (baseline)
--model Override model for replay
--diff Show diff vs original response

tokenpak debug

Toggle detailed request logging.

tokenpak debug on [--requests N]   # capture next N requests
tokenpak debug off
tokenpak debug status

Templates

tokenpak template

Manage prompt templates.

tokenpak template list
tokenpak template create NAME
tokenpak template use NAME [--var KEY=VALUE]
tokenpak template export NAME [--output FILE]
tokenpak template delete NAME

Recipes

tokenpak recipe

Manage compression recipes.

tokenpak recipe list
tokenpak recipe create NAME [--category CAT] [--domain-example EXAMPLE]
tokenpak recipe validate FILE
tokenpak recipe test FILE --input-file INPUT
tokenpak recipe benchmark FILE [--runs N]
tokenpak recipe install FILE
tokenpak recipe remove NAME

See Recipe Development for full details.

Audit & Compliance

tokenpak audit

View and export the audit log.

tokenpak audit list [--since DATE] [--user ID] [--model MODEL]
tokenpak audit export [--format json|csv] [--output FILE]
tokenpak audit prune [--older-than DAYS]

tokenpak compliance

Generate compliance reports.

tokenpak compliance report --standard soc2|gdpr|ccpa [--output FILE]
tokenpak compliance status

Configuration & Maintenance

tokenpak config

Get or set configuration values.

tokenpak config get KEY
tokenpak config set KEY VALUE
tokenpak config list
tokenpak config export [--output FILE]
tokenpak config reset

Common config keys:

Key Default Description
proxy.port 8766 Proxy listen port
proxy.passthrough_url OpenAI Default upstream URL
compression.enabled true Master compression switch
compression.level balanced minimal, balanced, aggressive
budget.monthly_usd null Monthly spend limit
budget.alert_at_pct 80 Alert threshold (%)
vault.watch false Auto re-index on changes

tokenpak prune

Remove old data from the local database.

tokenpak prune [--older-than DURATION] [--dry-run]
Flag Description
--older-than Duration string: 30d, 3m, 1y
--dry-run Show what would be deleted without deleting

Global Flags

These flags work with any command:

Flag Description
--json Output as JSON
--quiet Suppress non-essential output
--verbose Extra debug output
--config FILE Use alternate config file
--db FILE Use alternate database file
--version Show TokenPak version
--help Show command help
This site is open source. Improve this page.