Imported from CarlosJimenezPM/alcampo-cli (AGENTS.md). Install upstream with npx skills add CarlosJimenezPM/alcampo-cli. Copyright stays with the author.

AGENTS.md

This repo contains an unofficial personal CLI for Alcampo España.

Prime rules

• Be practical and safe.
• Do not checkout or pay.
• Do not alter real cart state without explicit --yes.
• Do not commit secrets or browser sessions.
• Treat curl.txt, *.curl, *.har, auth.json, and ~/.alcampo/auth.json as sensitive.
• Prefer trash over destructive deletion.

Current architecture

./alcampo is only a tiny entrypoint. Keep logic in modules:

alcampo_cli/config.py        paths, constants, base headers
alcampo_cli/http.py          imported browser session + HTTP requests
alcampo_cli/products.py      product search, normalization, favorites-first resolution
alcampo_cli/favorites.py     paginated favorites pull
alcampo_cli/basket.py        local basket state
alcampo_cli/cart.py          real Alcampo cart mutations
alcampo_cli/auth.py          Copy as cURL parser
alcampo_cli/aliases.py       exact local aliases
alcampo_cli/diff.py          local basket vs real cart diff
alcampo_cli/price_history.py local price snapshots/history
alcampo_cli/categories.py    category tree and category products
alcampo_cli/pricing.py       local basket file parsing/pricing
alcampo_cli/budget.py        budget guard
alcampo_cli/commands/*.py    argparse command handlers
alcampo_cli/cli.py           parser wiring

Product resolution behavior

Commands that resolve product names prefer:

1. Exact alias from ~/.alcampo/aliases.json.
2. Exact ID / local staple.
3. Local Alcampo favorite from ~/.alcampo/favorites.json.
4. Remote Alcampo search.

Use --no-favorites to bypass local favorites when testing raw search behavior. Refresh favorites with:

./alcampo favorites pull --limit 1000

Useful commands

./alcampo search leche --limit 5
./alcampo product 54178
./alcampo shop plan -f lista.txt --max 60
./alcampo shop apply --replace --max 60 --yes
printf 'leche\ncafe\npan\n' | ./alcampo batch -f - --per-term 1
printf '54178 1\n562075 2\n' | ./alcampo total -f -
./alcampo categories --id OC2112 --retailer --limit 3
./alcampo favorites pull --limit 1000
./alcampo favorites search zumo
./alcampo aliases list
./alcampo cart diff-local
./alcampo price history
./alcampo price config show
./alcampo price run-config
./alcampo basket breakfast --people 2 --days 3 --max 25 --replace
./alcampo auth status
./alcampo cart get

Shop plan/apply

Use ./alcampo shop plan -f lista.txt --max X for agent-friendly planning. It does not touch the cart. ./alcampo shop apply requires --yes and explicit --replace or --add; never checkout or pay.

Real cart commands

Real cart mutation commands require --yes:

./alcampo cart add zumo 1 --yes
./alcampo cart remove zumo 1 --yes
./alcampo cart clear --yes
./alcampo cart sync-local --yes
./alcampo cart set-many -f cesta.txt --max 30 --yes

cart set-many prices the file first and refuses before touching the cart if it exceeds --max.

Validation checklist

Before committing changes, run:

. .venv/bin/activate
python -m py_compile alcampo alcampo_cli/*.py alcampo_cli/commands/*.py
pytest -q
./alcampo --help
./alcampo search leche --limit 5
./alcampo product 54178
./alcampo shop plan -f lista.txt --max 60
./alcampo shop apply --replace --max 60 --yes
printf 'leche\ncafe\npan\n' | ./alcampo batch -f - --per-term 1
printf '54178 1\n562075 2\n' | ./alcampo total -f -
./alcampo categories --id OC2112 --retailer --limit 3
./alcampo favorites list --limit 3
./alcampo aliases list
./alcampo cart diff-local
./alcampo price history
./alcampo price config show
./alcampo price run-config
./alcampo basket show --json | python -m json.tool >/tmp/alcampo-basket.json
./alcampo auth status
./alcampo cart get

For real cart mutation, only test with explicit human approval and --yes.

Price snapshot config

Recurring snapshots are configured inside ~/.alcampo/price-config.json with ./alcampo price config .... ./alcampo price run-config runs only due jobs; cron/systemd should call that command rather than hard-coding individual price track commands. It should continue per-job on errors and record last_error in the config.

Notes

The CLI uses curl_cffi with Chrome impersonation because supermarket websites often reject basic HTTP clients.