CLI

Manage Persist stores, inspect data, and run operations from the command line.

Installation

The CLI is included with the TypeScript SDK:

npm install -g @cuitty/persist

After installation, the persist command is available globally.

Core commands

Store operations

# Create a new store
persist store create my-app --adapter sqlite --path ./data/my-app.db

# List all configured stores
persist store list

# Show store info (adapter, record count, sync status)
persist store info my-app

Records

# Put a record (value as JSON)
persist records put my-app user:1 '{"name":"Alice","role":"admin"}'

# Get a record
persist records get my-app user:1

# List records with prefix
persist records list my-app --prefix "user:" --limit 20

# Delete a record
persist records delete my-app user:1

Events

# Append an event
persist events append my-app audit '{"action":"login","userId":"1"}'

# List recent events
persist events list my-app --stream audit --limit 10

# Tail events in real-time
persist events tail my-app --stream audit

Key-Value

# Set a value
persist kv set my-app feature:dark-mode enabled

# Get a value
persist kv get my-app feature:dark-mode

# Delete a key
persist kv delete my-app feature:dark-mode

Sync commands

# Show sync status
persist sync status my-app

# Force a sync cycle
persist sync push my-app

# Show pending queue
persist sync queue my-app

Configuration file

The CLI reads from persist.config.ts in the current directory or from ~/.config/persist/config.ts globally. You can also pass --config path/to/config.ts explicitly.

# Initialize a config file in the current directory
persist init

# Validate the config file
persist config validate

Shell completions

Generate completion scripts for your shell:

# Bash
persist completions bash >> ~/.bashrc

# Zsh
persist completions zsh >> ~/.zshrc

# Fish
persist completions fish > ~/.config/fish/completions/persist.fish

Output formats

Most commands support --format for structured output:

persist records list my-app --format json   # JSON array
persist records list my-app --format csv    # CSV output
persist records list my-app --format table  # default: formatted table