hexr cache lets you inspect and manage the three-tier credential cache that powers hexr_tool() calls inside your agents. The cache operates at three levels — L1 in-memory, L2 in Valkey, and L3 full exchange with the cloud provider — and is designed to keep cloud credential round-trips below 1 ms for hot paths. Use hexr cache when you need to diagnose credential latency, force a full re-exchange after rotating secrets, or pull cache performance metrics for observability pipelines.
Usage
Subcommands
hexr cache status
Show the current state of each cached credential, including which cache tier is holding it, its TTL, and when it expires:
$ hexr cache status
Credential Cache Status:
┌──────────────────┬──────────┬──────────┬────────────┐
│ Service │ Tier │ TTL │ Expires │
├──────────────────┼──────────┼──────────┼────────────┤
│ aws_s3 │ L1 (mem) │ 12m │ 14:32 UTC │
│ gcp_bigquery │ L2 (val) │ 45m │ 15:07 UTC │
│ azure_storage │ expired │ — │ — │
└──────────────────┴──────────┴──────────┴────────────┘
Hit Rates (last 1h):
L1 (memory): 78.3%
L2 (Valkey): 18.4%
L3 (exchange): 3.3%
hexr cache clear
Evict all entries from L1 and L2. The next hexr_tool() call for any service will perform a full L3 credential exchange:
$ hexr cache clear
✓ L1 cache cleared (in-memory)
✓ L2 cache cleared (Valkey)
Note: Next hexr_tool() call will perform a full credential exchange.
Clearing the cache increases latency for the next set of hexr_tool() calls until entries are repopulated. In high-throughput agents, consider timing this during a low-traffic window.
hexr cache metrics
Export detailed cache performance metrics for the past 24 hours. Useful for dashboards, alerting, and debugging unexpected latency spikes:
$ hexr cache metrics
Cache Metrics (last 24h):
Total lookups: 12,847
L1 hits: 9,634 (75.0%)
L2 hits: 2,891 (22.5%)
L3 exchanges: 322 (2.5%)
Avg L1 latency: 0.001ms
Avg L2 latency: 2.1ms
Avg L3 latency: 142ms
Proactive refreshes: 48
Failed exchanges: 0
Cache tier reference
| Tier | Storage | Typical latency | Purpose |
|---|
| L1 | In-process memory | ~0.001 ms | Fastest path for hot credentials |
| L2 | Valkey (shared) | ~2 ms | Cross-process sharing within the pod |
| L3 | Cloud provider exchange | ~142 ms | Full SPIFFE-to-cloud credential exchange |
A healthy cache should show L1 hit rates above 70% for steady-state agents. A consistently low L1 rate may indicate that your agents are spawning too many short-lived processes, each with a fresh in-memory cache.