{"content":"# aux4/cache\n\nCache the output of any aux4 command with a configurable TTL. On subsequent identical calls within the TTL, the cached result is returned instantly instead of re-executing the command.\n\n## Installation\n\n``bash\naux4 aux4 pkger install aux4/cache\n`\n\n## Quick Start\n\n`bash\n# Run a command with caching (default 300s TTL)\naux4 cache db execute --query \"SELECT * FROM users\"\n\n# Second call returns cached result instantly\naux4 cache db execute --query \"SELECT * FROM users\"\n\n# Set a custom TTL\naux4 cache --cacheDuration 60 curl request https://api.example.com/data\n`\n\n## Configuration\n\nCreate a config.yaml to define per-command cache duration patterns:\n\n`yaml\nconfig:\n cache:\n defaultDuration: 300\n cacheDir: .aux4.cache\n patterns:\n - match: \"db execute *\"\n duration: 300\n - match: \"db stream *\"\n duration: 120\n - match: \"curl *\"\n duration: 600\n`\n\nUse it with --configFile:\n\n`bash\naux4 cache --configFile config.yaml db execute --query \"SELECT 1\"\n`\n\n### Duration Resolution Priority\n\n1. Explicit --cacheDuration flag (if > 0)\n2. First matching pattern from config.yaml\n3. defaultDuration from config.yaml\n4. Hardcoded fallback: 300 seconds\n\n### Pattern Matching\n\nPatterns use prefix matching with as a wildcard suffix:\n\n- \"db execute \" matches any command starting with db execute\n- \"curl *\" matches any command starting with curl\n- \"config get test/host\" matches that exact command\n\n## Commands\n\n### aux4 cache <command>\n\nExecute a command with caching. If a cached result exists and is within the TTL, it is returned without re-executing. Otherwise, the command runs, its output is cached, and the result is printed.\n\n`bash\naux4 cache [--cacheDuration <seconds>] [--cacheDir <dir>] [--configFile <file>] <command...>\n`\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| --cacheDuration | 0 (auto) | Cache duration in seconds. 0 means resolve from config or use 300s default |\n| --cacheDir | .aux4.cache | Directory for cache files |\n| --configFile | (none) | Path to config.yaml for pattern-based durations |\n| --refresh | false | Force re-execute and refresh the cached entry |\n\n### aux4 cache clear [pattern]\n\nRemove cached entries. Without a pattern, all entries are removed. With a pattern, only matching entries are cleared.\n\n`bash\n# Clear all cached entries\naux4 cache clear\n\n# Clear entries matching a pattern\naux4 cache clear \"db execute *\"\n`\n\n### aux4 cache list\n\nList all cached entries with their age, TTL, and validity status. Output is JSON.\n\n`bash\naux4 cache list\n`\n\n`json\n[\n {\n \"command\": \"db execute --query SELECT 1\",\n \"age\": 45,\n \"duration\": 300,\n \"remaining\": 255,\n \"valid\": true\n }\n]\n`\n\n## Cache Storage\n\nCache files are stored as JSON in the cache directory (default .aux4.cache/). Each entry is a file named by the SHA256 hash of the command string:\n\n`\n.aux4.cache/\n a1b2c3d4...json\n e5f6g7h8...json\n``\n\nWrites are atomic (temp file + rename) to prevent partial reads.\n"}