apicache-cli-av

Tiny Typer CLI that fetches an API resource and caches results in SQLite (SQLModel). Use it as a command-line tool or import its library in other projects.

Features

• Fetch JSON from an HTTP API (configurable base URL)
• Optional API key header
• SQLite-backed cache for idempotent reads
• Save output to an auto-named file or a specific file
• Simple Docker image for zero-setup runs

---

Install (PyPI)

Recommended for CLI users: pipx

• pipx ensures isolated CLI installs and adds the command to your PATH.

pip install --upgrade pipx
pipx install apicache-cli-av
apicache-cli-av --help

Standard pip (inside a virtual environment)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -U apicache-cli-av
apicache-cli-av --help

Install from TestPyPI (if you’re testing pre-releases)

pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple apicache-cli-av

---

Usage

Basic fetch (prints JSON and writes a file)

apicache-cli-av fetch --resource posts --id 1

• By default, the tool writes to an auto-named file under data/, e.g., data/posts_1.json.
• Use --output-file to write to an exact path, or --output-dir to change the default directory.

Save to a specific file

apicache-cli-av fetch -r posts -i 1 --output-file data/posts_1.json

Save to a different directory with auto filename

apicache-cli-av fetch -r posts -i 1 --output-dir out

Open the file after saving (Windows will open with the OS default app)

apicache-cli-av fetch -r posts -i 1 --output-dir data --open

Bypass cache

apicache-cli-av fetch -r posts -i 1 --no-cache

Specify a base URL

apicache-cli-av fetch -r items -i 42 --base-url https://api.example.com

Pass an API key (prefer environment variable)

# Windows PowerShell
$env:APICACHE_API_KEY = "your-api-key"
apicache-cli-av fetch -r items -i 42

# Or via flag (less secure; may show in history/process list)
apicache-cli-av fetch -r items -i 42 --api-key "your-api-key"

Environment variables

• APICACHE_API_KEY: API key to send (usually as Authorization: Bearer )
• API_BASE_URL: Default base URL if not passed via --base-url
• APICACHE_OUTPUT_DIR: Default directory for saved JSON files (when no --output-file)
• APICACHE_DB_PATH: SQLite path for the cache (defaults to data/cache.db)

---

Docker

Pull the image (replace the repository if you use GHCR or a different namespace)

docker pull docker.io/asvarnon/apicache:latest

Run the CLI (ephemeral container)

docker run --rm docker.io/asvarnon/apicache:latest apicache-cli-av --help

Persist cache and outputs to your host

mkdir -Force data | Out-Null
docker run --rm `
  -v ${PWD}/data:/app/data `
  docker.io/asvarnon/apicache:latest `
  apicache-cli-av fetch -r posts -i 1 --output-dir /app/data

Provide an API key at runtime

docker run --rm `
  -e APICACHE_API_KEY="your-api-key" `
  docker.io/asvarnon/apicache:latest `
  apicache-cli-av fetch -r items -i 42

Notes

• --open won’t launch desktop apps from inside a container. Save to a mounted volume and open the file on your host.
• Use a specific tag (e.g., :v1.2.3 or :) for reproducible runs.

---

Library usage

from apicache_cli_av.api import APIClient

client = APIClient()  # or APIClient(base_url="https://api.example.com", api_key="...")
data = client.fetch("posts", 1)
print(data)

---

Development

Setup

poetry install
poetry run pytest -q

Local CLI

poetry run apicache-cli-av --help

Build and publish (manual)

poetry build
# TestPyPI
poetry run twine upload --repository testpypi dist/*
# PyPI
poetry run twine upload dist/*

---

Troubleshooting

• Typer/Click error like “Parameter.make_metavar() missing 1 required positional argument: 'ctx'”

  • Ensure Click < 8.2 with Typer 0.12 (this project pins click >=8.1,<8.2).

• TestPyPI upload 403

  • Bump version; ensure you’re using username token and a valid token for the correct index.

• Import errors for utils

  • Package path is apicache_cli_av; make sure relative imports are used within the package and that the project is installed (pip/poetry) or PYTHONPATH includes src/ during debugging.

---

License

MIT