Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hexr.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

hexr cache <subcommand>

​
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

TierStorageTypical latencyPurpose
L1In-process memory~0.001 msFastest path for hot credentials
L2Valkey (shared)~2 msCross-process sharing within the pod
L3Cloud provider exchange~142 msFull 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.