CLI Reference

All commands in the keplor binary.

keplor run

Start the HTTP ingestion server.

$ keplor run [OPTIONS]

Options:
  -c, --config <PATH>    Config file [default: keplor.toml]

If the config file doesn't exist, defaults are used. Binds to 0.0.0.0:8080 and creates keplor.db.

keplor migrate

Apply database migrations without starting the server.

$ keplor migrate --db /var/lib/keplor/keplor.db
migrations applied to /var/lib/keplor/keplor.db

keplor query

Query stored events from the command line.

$ keplor query [OPTIONS]

Options:
  --user-id <ID>       Filter by user
  --model <NAME>       Filter by model
  --provider <KEY>     Filter by provider
  --source <NAME>      Filter by source
  --limit <N>          Max results [default: 20]
  -d, --db <PATH>      Database path [default: keplor.db]

Example:

$ keplor query --provider openai --limit 5
ID                           PROVIDER       MODEL                   TOKENS       COST ($)
--------------------------------------------------------------------------------------------
01J5XQKR...                  openai         gpt-4o                     700     0.00625000
01J5XPBN...                  openai         gpt-4o-mini                340     0.00012750

2 event(s)

keplor stats

Print storage statistics.

$ keplor stats
=== Keplor Storage Statistics ===
Database:             keplor.db
Total events:         12,847
Database size:        4.2 MB

keplor gc

Delete events older than a threshold.

$ keplor gc --older-than-days 30
GC complete: deleted 4,291 events (cutoff: 30 days ago)

Schedule via cron for automatic cleanup:

# crontab -e
0 3 * * * /usr/local/bin/keplor gc --older-than-days 90 --db /var/lib/keplor/keplor.db

keplor archive

Manually archive old events to S3/R2 (requires --features s3).

$ keplor archive --config keplor.toml --older-than-days 7
Archived 4,291 events in 3 files (1.2 MB compressed)

Useful for one-off archival outside the automatic hourly cycle.

keplor archive_status

Show archive manifest — what’s been archived to S3/R2.

$ keplor archive_status --config keplor.toml
=== Archive Status ===
User        Day          Events  Compressed
alice       2026-04-12     847    42.1 KB
alice       2026-04-13     923    45.3 KB
bob         2026-04-12     512    28.7 KB
Total: 3 archive files, 2,282 events