- Upstash Redis Key-Value Store
- Interact with Upstash's Redis-compatible key-value store using the REST interface.
- Script Location
- bun run scripts/upstash-client.ts
- <
- command
- >
- [
- args
- ..
- .
- ]
- IMPORTANT
-
- Always run with
- bun run
- , not directly.
- Configuration
- Environment Variables
- The script uses these environment variables by default:
- UPSTASH_REDIS_REST_URL
- - The Upstash REST API URL
- UPSTASH_REDIS_REST_TOKEN
- - The Upstash REST API token
- Overriding Credentials
- If the user provides credentials from another source (conversation context, a file, etc.), use the
- --url
- and
- --token
- flags to override environment variables:
- bun run scripts/upstash-client.ts
- --url
- "https://..."
- --token
- "AX..."
- GET mykey
- Priority
- Command-line flags > Environment variables Command Reference String Commands
Get/Set
GET < key
SET < key
< value
[ --ex seconds ] [ --px ms ] [ --nx ] [ --xx ] [ --keepttl ] [ --get ] SETNX < key
< value
Set if not exists
SETEX < key
< seconds
< value
Set with expiration
Multiple keys (key/value pairs)
MGET < key 1
[ key2 .. . ] MSET < key 1
< val 1
[ key2 val2 .. . ] MSETNX < key 1
< val 1
[ key2 val2 .. . ]
Set all if none exist
Counters
INCR < key
INCRBY < key
< increment
INCRBYFLOAT < key
< increment
DECR < key
DECRBY < key
< decrement
String manipulation
APPEND < key
< value
STRLEN < key
GETRANGE < key
< start
< end
SETRANGE < key
< offset
< value
Hash Commands Hashes store field-value pairs. Pass fields and values as alternating arguments:
Set hash fields (field/value pairs)
HSET < key
< field 1
< val 1
[ field2 val2 .. . ] HSETNX < key
< field
< value
Set field if not exists
Get hash fields
HGET < key
< field
HMGET < key
< field 1
[ field2 .. . ] HGETALL < key
Hash operations
HDEL < key
< field 1
[ field2 .. . ] HEXISTS < key
< field
HKEYS < key
HVALS < key
HLEN < key
HINCRBY < key
< field
< increment
HINCRBYFLOAT < key
< field
< increment
HSCAN < key
< cursor
[ MATCH pattern ] [ COUNT count ] Examples:
Store user data
bun run scripts/upstash-client.ts HSET user:1 name "John" email "john@example.com" age 30
Get single field
bun run scripts/upstash-client.ts HGET user:1 name
Get all fields
bun run scripts/upstash-client.ts HGETALL user:1
Increment numeric field
bun run scripts/upstash-client.ts HINCRBY user:1 age 1 List Commands Lists are ordered collections. Values are pushed/popped from left (head) or right (tail):
Push elements
LPUSH < key
< val 1
[ val2 .. . ]
Push to head
RPUSH < key
< val 1
[ val2 .. . ]
Push to tail
LPUSHX < key
< val 1
[ val2 .. . ]
Push if list exists
RPUSHX < key
< val 1
[ val2 .. . ]
Pop elements
LPOP < key
[ count ] RPOP < key
[ count ]
Access elements
LRANGE < key
< start
< stop
Get range (0 = first, -1 = last)
LLEN < key
LINDEX < key
< index
Modify
LSET < key
< index
< value
LREM < key
< count
< value
Remove count occurrences
LTRIM < key
< start
< stop
Keep only range
LINSERT < key
< BEFORE | AFTER
< pivot
< value
LPOS < key
< value
LMOVE < src
< dst
< LEFT | RIGHT
< LEFT | RIGHT
Examples:
Create a task queue
bun run scripts/upstash-client.ts RPUSH tasks "task1" "task2" "task3"
Get all tasks
bun run scripts/upstash-client.ts LRANGE tasks 0 -1
Pop task from front (FIFO queue)
bun run scripts/upstash-client.ts LPOP tasks
Pop task from back (LIFO stack)
bun run scripts/upstash-client.ts RPOP tasks Set Commands Sets store unique, unordered members:
Add/remove members
SADD < key
< member 1
[ member2 .. . ] SREM < key
< member 1
[ member2 .. . ]
Query
SMEMBERS < key
SISMEMBER < key
< member
SMISMEMBER < key
< member 1
[ member2 .. . ] SCARD < key
Random access
SPOP < key
[ count ] SRANDMEMBER < key
[ count ]
Set operations
SINTER < key 1
[ key2 .. . ] SINTERSTORE < dest
< key 1
[ key2 .. . ] SUNION < key 1
[ key2 .. . ] SUNIONSTORE < dest
< key 1
[ key2 .. . ] SDIFF < key 1
[ key2 .. . ] SDIFFSTORE < dest
< key 1
[ key2 .. . ] SMOVE < src
< dst
< member
SSCAN < key
< cursor
[ MATCH pattern ] [ COUNT count ] Examples:
Add tags
bun run scripts/upstash-client.ts SADD article:1:tags "javascript" "redis" "nodejs"
Check membership
bun run scripts/upstash-client.ts SISMEMBER article:1:tags "javascript"
Get all members
bun run scripts/upstash-client.ts SMEMBERS article:1:tags
Find common tags between articles
bun run scripts/upstash-client.ts SINTER article:1:tags article:2:tags Sorted Set Commands Sorted sets store members with scores for ranking:
Add members (score/member pairs)
ZADD < key
< score 1
< member 1
[ score2 member2 .. . ] [ --nx ] [ --xx ] [ --gt ] [ --lt ] [ --ch ]
Remove
ZREM < key
< member 1
[ member2 .. . ] ZREMRANGEBYRANK < key
< start
< stop
ZREMRANGEBYSCORE < key
< min
< max
Scores and ranks
ZSCORE < key
< member
ZMSCORE < key
< member 1
[ member2 .. . ] ZRANK < key
< member
Rank (low to high)
ZREVRANK < key
< member
Rank (high to low)
ZINCRBY < key
< increment
< member
Range queries
ZRANGE < key
< start
< stop
[ --withscores ] [ --rev ] [ --byscore ] [ --bylex ] ZRANGEBYSCORE < key
< min
< max
[ --withscores ] [ --limit off,count ] ZREVRANGE < key
< start
< stop
[ --withscores ] ZREVRANGEBYSCORE < key
< max
< min
[ --withscores ] [ --limit off,count ]
Counting
ZCARD < key
ZCOUNT < key
< min
< max
Pop
ZPOPMIN < key
[ count ] ZPOPMAX < key
[ count ]
Set operations
ZINTERSTORE < dest
< numkeys
< key 1
[ key2 .. . ] ZUNIONSTORE < dest
< numkeys
< key 1
[ key2 .. . ] ZSCAN < key
< cursor
[ MATCH pattern ] [ COUNT count ] Examples:
Create leaderboard (score member pairs)
bun run scripts/upstash-client.ts ZADD leaderboard 1000 "player1" 1500 "player2" 1200 "player3"
Get top 3 with scores (highest first)
bun run scripts/upstash-client.ts ZRANGE leaderboard 0 2 --rev --withscores
Get player's rank
bun run scripts/upstash-client.ts ZREVRANK leaderboard "player2"
Increment player's score
bun run scripts/upstash-client.ts ZINCRBY leaderboard 100 "player1"
Get players with scores between 1000 and 1500
bun run scripts/upstash-client.ts ZRANGEBYSCORE leaderboard 1000 1500 --withscores Key Commands
Delete
DEL < key 1
[ key2 .. . ] UNLINK < key 1
[ key2 .. . ]
Async delete
Existence/Type
EXISTS < key 1
[ key2 .. . ] TYPE < key
Expiration
EXPIRE < key
< seconds
EXPIREAT < key
< timestamp
PEXPIRE < key
< milliseconds
PEXPIREAT < key
< timestamp
TTL < key
PTTL < key
PERSIST < key
Remove expiration
Rename
RENAME < key
< newkey
RENAMENX < key
< newkey
Search
KEYS < pattern
Use with caution in production
SCAN < cursor
[ MATCH pattern ] [ COUNT count ]
Other
COPY < src
< dst
DUMP < key
TOUCH < key 1
[ key2 .. . ] RANDOMKEY OBJECT ENCODING | FREQ | IDLETIME | REFCOUNT < key
Examples:
Set key with 1 hour expiration
bun run scripts/upstash-client.ts SET session:abc "data" bun run scripts/upstash-client.ts EXPIRE session:abc 3600
Or in one command
bun run scripts/upstash-client.ts SET session:abc "data" --ex 3600
Check TTL
bun run scripts/upstash-client.ts TTL session:abc
Scan keys matching pattern
bun run scripts/upstash-client.ts SCAN 0 MATCH "user:*" COUNT 100 Server Commands PING [ message ] ECHO < message
DBSIZE TIME INFO [ section ] FLUSHDB
Delete all keys in current DB (DANGEROUS)
FLUSHALL
Delete all keys in all DBs (DANGEROUS)
Command Options SET Options --ex < seconds
Expire in seconds
--px < ms
Expire in milliseconds
--exat < ts
Expire at Unix timestamp (seconds)
--pxat < ts
Expire at Unix timestamp (ms)
--nx
Only set if key does not exist
--xx
Only set if key exists
--keepttl
Retain existing TTL
--get
Return old value
ZADD Options --nx
Only add new members
--xx
Only update existing members
--gt
Only update if new score > current
--lt
Only update if new score < current
--ch
Return number of changed elements
ZRANGE Options --withscores
Include scores in output
--byscore
Range by score instead of rank
--bylex
Range by lexicographical order
--rev
Reverse order
--limit off,count
Limit results (e.g., --limit 0,10)
- Output Format
- String values
-
- Printed directly
- null/nil
-
- Prints
- (nil)
- Objects/arrays
- Pretty-printed as JSON Confirmation Behaviour Default: Ask for Confirmation Before executing any destructive operation (write, modify, or delete), you MUST ask the user for confirmation. This includes: Write operations: SET, SETNX, SETEX, PSETEX, MSET, MSETNX HSET, HSETNX LPUSH, RPUSH, LPUSHX, RPUSHX, LSET, LINSERT SADD ZADD Modify operations: INCR, INCRBY, INCRBYFLOAT, DECR, DECRBY APPEND, SETRANGE HINCRBY, HINCRBYFLOAT LREM, LTRIM, LMOVE ZINCRBY Delete operations: DEL, UNLINK HDEL LPOP, RPOP SREM, SPOP, SMOVE ZREM, ZREMRANGEBYRANK, ZREMRANGEBYSCORE, ZPOPMIN, ZPOPMAX FLUSHDB, FLUSHALL (extra caution) TTL/Rename operations: EXPIRE, EXPIREAT, PEXPIRE, PEXPIREAT, PERSIST RENAME, RENAMENX Example confirmation prompt: "I'm about to HSET user:1 with fields {name: "John", email: "john@example.com"} . Proceed?" YOLO Mode: Skip Confirmation If the user indicates they do not want to be asked for confirmation, respect this for all subsequent operations. Indicators include: "YOLO mode" "Don't ask for confirmation" "You're free to make changes without asking" "Just do it" "No need to confirm" "Auto-approve" or "auto-confirm" Any similar phrasing indicating blanket approval Once YOLO mode is activated, proceed with destructive operations without asking, but still inform the user what was done. Example: Set user:1 with {name: "John", email: "john@example.com"} - done. Error Handling If credentials are missing or invalid, the script will exit with an error message. Ensure the user has configured either: Environment variables ( UPSTASH_REDIS_REST_URL , UPSTASH_REDIS_REST_TOKEN ) Or provides credentials via --url and --token flags When to Use This Skill User explicitly asks to store or retrieve data from Upstash/Redis Need to persist data across conversations or sessions Implementing caching for expensive operations Maintaining counters, rate limits, or statistics Storing user preferences or session data Building leaderboards or rankings (sorted sets) Managing queues or task lists (lists) Tagging or categorisation (sets) Storing structured objects (hashes) Any scenario requiring fast key-value storage