The Aeron Cache CLI · Aeron Cache

Why a CLI

When you are debugging a cache, wiring up a CI step, or just want to poke at state without writing code, the terminal is the fastest path. The Aeron Cache CLI is a thin, fast client over the REST API that exposes the full cache and counter surface as plain commands — create, insert, get, list, stats, and the counter equivalents — so any shell can drive the cache.

It is built in Rust 🦀 using Clap for argument parsing, Dialoguer for prompts, Reqwest for HTTP, and Serde for JSON. There’s an asciinema demo if you’d rather watch it first.

Install

brew tap bhf/aeron-cache-cli
brew install aeron-cache-cli

Configuration

By default the CLI talks to a backend at http://localhost:7070/api/v1 — exactly what the local monolith exposes. Point it elsewhere with the --api-url flag or the AERON_CACHE_API_URL environment variable:

# Flag, per invocation:
aeron-cache --api-url http://otherhost:7070/api/v1 stats

# Environment variable, for a whole session:
export AERON_CACHE_API_URL=http://otherhost:7070/api/v1
aeron-cache stats

Add --help to any command for its full signature.

A worked session

Create a cache, write to it, read it back, then inspect:

aeron-cache create orders
aeron-cache insert orders order:1001 "shipped"
aeron-cache get orders order:1001
aeron-cache list-caches
aeron-cache stats

A representative run:

$ aeron-cache create orders
Created cache 'orders' (SUCCESS)

$ aeron-cache insert orders order:1001 "shipped"
orders/order:1001 <- shipped (SUCCESS)

$ aeron-cache get orders order:1001
order:1001 = shipped

$ aeron-cache list-caches
orders (1 item)

$ aeron-cache stats
caches=1 items=1 ops=2 errors=0

Counters follow the same rhythm with the counter commands — e.g. create-counter-cache metrics, increment-counter metrics requests, counter-stats.

Command reference

Cache commands

Command	Description
`create <name>`	Create a new cache
`delete <name>`	Delete a cache
`get-cache <name>`	Get all items from a cache
`clear-cache <name>`	Clear all items from a cache
`insert <name> <key> <value>`	Insert an item into a cache
`insert-timed <name> <key> <value> <ttl>`	Insert an item with a TTL (milliseconds) into a cache
`get <name> <key>`	Get an item from a cache
`remove <name> <key>`	Remove an item from a cache
`cancel-removal <name> <key>`	Cancel a scheduled removal of an item
`list-caches`	List all available caches and their item count
`stats`	Get global cache statistics

Counter commands

Command	Description
`create-counter-cache <name>`	Create a new counter cache
`delete-counter-cache <name>`	Delete a counter cache
`get-counter-cache <name>`	Get all counters from a counter cache
`clear-counter-cache <name>`	Clear all counters from a counter cache
`put-counter <name> <key> <value>`	Put a counter into a counter cache
`put-timed-counter <name> <key> <value> <ttl>`	Put a counter with a TTL (milliseconds) into a counter cache
`get-counter <name> <key>`	Get a single counter from a counter cache
`delete-counter <name> <key>`	Delete a single counter from a counter cache
`increment-counter <name> <key> [amount]`	Increment a counter (defaults to 1)
`decrement-counter <name> <key> [amount]`	Decrement a counter (defaults to 1)
`set-counter <name> <key> <value>`	Set a counter to a given value
`cancel-counter-removal <name> <key>`	Cancel a scheduled removal of a counter
`list-counter-caches`	List all available counter caches and their item count
`counter-stats`	Get global counter cache statistics

Timed entries and cancellation

insert-timed and put-timed-counter take a TTL in milliseconds, scheduling a removal timer. Use cancel-removal (or cancel-counter-removal) to keep the entry alive — the pattern for TTL-backed session and presence stores that extend on activity:

aeron-cache insert-timed sessions user:42 active 60000
aeron-cache cancel-removal sessions user:42

Where to next

Getting Started — install the monolith the CLI talks to, and the same operations through HTTP and the client libraries.
API overview — the REST API the CLI is built on, including request and response shapes.

Takeaway: every CLI command is a one-liner over /api/v1 — scriptable, CI-friendly, and pointed anywhere with --api-url or AERON_CACHE_API_URL.