ephpm kv

Inspect or manipulate the KV store on a running ePHPm server. Speaks the RESP2 protocol — the same one that PHP clients (Predis, phpredis) use, so you’re seeing the live store as PHP sees it.

Synopsis

ephpm kv [--host HOST] [--port PORT] [--password PW] [--user NAME] <subcommand> [args]

Like --host and --port, these are flags of ephpm kv itself, so they go before the subcommand.

The server must be configured with [kv.redis_compat] enabled = true for these commands to connect.

Authentication

The RESP listener requires AUTH as soon as either [kv.redis_compat] password or [kv] secret is set — until a connection authenticates, every command except AUTH and QUIT is answered with -NOAUTH Authentication required. There are two server-side modes:

Single password ([kv.redis_compat] password) — pass --password, or set EPHPM_KV_PASSWORD and leave the flag off:

ephpm kv --password "$KV_PASSWORD" keys '*'

export EPHPM_KV_PASSWORD=...
ephpm kv keys '*'

Per-site HMAC ([kv] secret together with [server] sites_dir) — the server expects AUTH <hostname> <HMAC-SHA256(secret, hostname)> and scopes the connection to that vhost’s store. The derived password is the same value ePHPm injects into PHP as EPHPM_REDIS_PASSWORD, so pass it with --user:

ephpm kv --user blog.example.com --password "$DERIVED" keys '*'

The CLI does not derive that value itself — it never reads [kv] secret.

Limitation: ephpm deploy and ephpm cache reset accept --password but not --user. They write opcache:version:*, which the server’s OPcache watcher reads from the default store, and a site-scoped HMAC connection can only reach one vhost’s store. Under per-site HMAC auth there is currently no CLI route to those keys.

Subcommands

ping

Checks the connection.

ephpm kv ping
# PONG

keys [PATTERN]

Lists keys matching a glob pattern. Default pattern is *.

ephpm kv keys              # all keys
ephpm kv keys 'session:*'  # all session keys
ephpm kv keys 'cache:user:*'

get <KEY>

Reads a value.

ephpm kv get mykey
ephpm kv get session:abc123

set <KEY> <VALUE> [--ttl SECS]

Writes a value. Optionally sets a TTL in seconds.

ephpm kv set greeting "hello"
ephpm kv set session:abc123 '{"user":1}' --ttl 3600

del <KEY>...

Deletes one or more keys.

ephpm kv del mykey
ephpm kv del key1 key2 key3

incr <KEY> [--by N]

Atomic increment. Default delta is 1.

ephpm kv incr page:views
ephpm kv incr counter --by 10

ttl <KEY>

Reports TTL info: a positive number (seconds), -1 (no expiry), or -2 (key missing).

ephpm kv ttl session:abc123

Common patterns

# Debug rate limiting
ephpm kv get "ratelimit:$user_id"
ephpm kv ttl "ratelimit:$user_id"

# Count active sessions
ephpm kv keys 'session:*' | wc -l

# Clear all sessions
ephpm kv keys 'session:*' | xargs -r ephpm kv del

# Connect to a remote instance
ephpm kv --host 10.0.1.5 --port 6379 keys '*'

# Connect to a password-protected listener
ephpm kv --host 10.0.1.5 --password "$KV_PASSWORD" keys '*'

See also

• KV from PHP — the ephpm_kv_* SAPI functions
• KV store architecture