Cache¶

Datasets and collections are each fetched in a single API call and cached locally as JSON. Filtering is done entirely client-side against this cache, which makes repeated queries fast and reduces API load.

Cache behavior¶

Datasets and collections are cached independently
The cache has a default TTL of 24 hours (86400 seconds)
When the cache is valid, commands read from disk instead of calling the API
When the API is unreachable, stale cached data is used as a fallback with a warning
Cache files are stored in the OS-appropriate cache directory (e.g., ~/.cache/cxg/ on Linux, ~/Library/Caches/cxg/ on macOS)

Managing the cache¶

# Check cache status (path, age, size, dataset count)
cxg cache status

# Force a refresh on the next query
cxg list --refresh

# Delete the cache
cxg cache clear

Configuration¶

Cache behavior can be customized in the config file or with environment variables. Settings are resolved in this order: environment variable > config file > default.

# Via config file
cxg config set cache.ttl 3600
cxg config set cache.dir ~/my-cache

# Via environment variables
export CXG_CACHE_TTL=3600
export CXG_CACHE_DIR=~/my-cache

Set TTL to 0 to disable caching entirely.