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]
      --json-logs        Emit structured JSON logs (for log aggregation)

If the config file doesn’t exist, defaults are used. Binds to 0.0.0.0:8080 and creates the KeplorDB data directory at ./keplor_data with one segment tree per retention tier.

keplor migrate

Verify or initialise a data directory. Opens the store, creating per-tier engines if missing, and refuses to mount a directory written under a mismatched schema id. Idempotent — safe to run repeatedly.

$ keplor migrate --data-dir /var/lib/keplor
data dir ready at /var/lib/keplor (schema id verified)

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, --data-dir <DIR>    KeplorDB data directory [default: ./keplor_data]

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 per-tier storage statistics.

$ keplor stats --data-dir /var/lib/keplor
=== Keplor Storage Statistics ===
Data dir:             /var/lib/keplor
Total events:         12,847
Total bytes on disk:  4.2 MB
Per tier:
  free  segments=128  events=8,401  bytes=2.7 MB
  pro   segments=42   events=4,123  bytes=1.4 MB
  team  segments=4    events=323    bytes=120 KB

keplor gc

Delete events older than a threshold. Segment-granular — drops whole segments whose events are entirely older than the cutoff.

$ keplor gc --older-than-days 30 --data-dir /var/lib/keplor
GC complete: tier=free segments_deleted=24 bytes_freed=1.1 MB
GC complete: tier=pro  segments_deleted=8  bytes_freed=312 KB

Schedule via cron for automatic cleanup if you’ve disabled the in-process GC loop:

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

keplor rollup

Force a WAL checkpoint — rotates the active WAL into a sealed segment so post-write queries see the events immediately. The legacy --days flag is accepted for compatibility but is now a no-op (rollups are accumulated on every write).

$ keplor rollup --data-dir /var/lib/keplor
WAL checkpointed: 3 tiers flushed

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 --data-dir /var/lib/keplor
=== 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, 116.1 KB