Cache — Local Key-Value Cache Manager#

A lightweight, file-backed key-value cache with TTL (time-to-live) support, search, bulk import/export, and statistics. Ideal for caching API responses, computed results, or any ephemeral data that benefits from quick local retrieval.

Prerequisites#

• Python 3.6+
• Bash 4+

Data Storage#

Cache entries are stored in ~/.cache-tool/data.jsonl (note: uses cache-tool to avoid conflicts with ~/.cache). Each line is a JSON object with fields: key, value, ttl, created_at, expires_at, tags, etc.

Configuration lives in ~/.cache-tool/config.json.

Commands#

Run via: bash scripts/script.sh <command> [options]

CommandDescriptionsetStore a key-value pair with optional TTL and tagsgetRetrieve the value for a given keydeleteRemove a key from the cachelistList all cache entries (with optional tag filter)flushDelete all cache entries or those matching a patternttlCheck or update the TTL for an existing keystatsShow cache statistics (size, hit/miss ratio, memory)exportExport the cache to a JSON fileimportImport cache entries from a JSON filesearchSearch keys or values by substring or regexconfigView or update cache settings (default TTL, max size)helpShow usage informationversionPrint the tool version

Usage Examples#

bash

# Set a simple key-value pair
bash scripts/script.sh set --key api_response --value '{"status":"ok"}' --ttl 3600

# Set with tags
bash scripts/script.sh set --key user:42 --value '{"name":"Kelly"}' --tags user,profile

# Get a value
bash scripts/script.sh get --key api_response

# Delete a key
bash scripts/script.sh delete --key old_data

# List all entries
bash scripts/script.sh list

# List entries by tag
bash scripts/script.sh list --tag user

# Check remaining TTL
bash scripts/script.sh ttl --key api_response

# Update TTL
bash scripts/script.sh ttl --key api_response --set 7200

# Flush all entries
bash scripts/script.sh flush

# Flush by pattern
bash scripts/script.sh flush --pattern "user:*"

# Search by key pattern
bash scripts/script.sh search --query "api_" --field key

# Show cache stats
bash scripts/script.sh stats

# Export cache
bash scripts/script.sh export --output cache_backup.json

# Import cache
bash scripts/script.sh import --input cache_backup.json

# Configure defaults
bash scripts/script.sh config --set default_ttl=3600 --set max_entries=10000

Notes#

• Expired entries are lazily cleaned: they are skipped on get and purged during flush or stats.
• The search command supports both simple substring matching and Python regex patterns.
• import merges entries; existing keys are overwritten.
• stats reports total entries, expired count, active count, and approximate data size.

Output Format#

get returns the raw value to stdout. All other commands return JSON objects with status and metadata.

---

Powered by BytesAgain | bytesagain.com | hello@bytesagain.com