redis-cli --scan: Usage, Options & Common CI Errors
redis-cli --scan walks the keyspace incrementally instead of all at once.
redis-cli --scan is the safe way to enumerate keys in CI, where KEYS * can stall the server. It is most often piped into xargs to bulk-delete or inspect matching keys.
What it does
The --scan mode drives the SCAN cursor under the hood, returning keys in batches so the server never blocks on a single command. It optionally filters by glob pattern and is the production-safe alternative to KEYS.
Common usage
redis-cli -h 127.0.0.1 --scan
redis-cli -h 127.0.0.1 --scan --pattern 'session:*'
redis-cli -h 127.0.0.1 --scan --pattern 'tmp:*' | xargs -r redis-cli -h 127.0.0.1 DEL
redis-cli -h 127.0.0.1 --scan --count 1000 # bigger batchesOptions
| Flag | What it does |
|---|---|
| --scan | Iterate the keyspace with SCAN |
| --pattern <glob> | Only keys matching the pattern |
| --count <N> | Hint how many keys per SCAN batch |
| -h <host> / -a <pass> | Connect / authenticate |
Common errors in CI
Prefer --scan over KEYS *: KEYS scans the entire keyspace in one blocking call and can freeze a large server, failing health checks mid-job. When piping to DEL, use xargs -r so an empty match does not run redis-cli DEL with no keys (which errors "wrong number of arguments"). --pattern is matched server-side, so quote the glob to keep the shell from expanding it. NOAUTH still applies - authenticate first on a protected server.