CLI Reference

The sirr CLI is a single binary for interacting with a sirrd server. It talks over HTTP using a bearer token for authentication.

To run the server, install sirrd — the Sirr daemon. The sirr CLI is the client only.

Configure the CLI with two environment variables:

SIRR_SERVER -- the URL of your Sirr instance (default http://localhost:39999)
SIRR_TOKEN -- the bearer token matching the server's SIRR_MASTER_KEY

Environment setup

export SIRR_SERVER="http://localhost:39999"
export SIRR_TOKEN="your-master-key"

sirr push

Push a secret to the server. Accepts a single KEY=VALUE pair or an entire .env file for batch upload.

Usage

sirr push KEY=VALUE [options]
sirr push .env [options]

Name
--ttl
Type
duration
Description
Time-to-live before the secret self-destructs. See TTL format below.
Name
--reads
Type
number
Description
Maximum number of reads before the secret is burned. Once the limit is reached, the secret is permanently destroyed.

Single secret

sirr push DB_URL="postgres://user:pass@db:5432/app" \
  --ttl 1h \
  --reads 1

Batch push from .env file

# Pushes every key-value pair in the file
sirr push .env --ttl 24h

When pushing a .env file, each line is stored as a separate secret on the server. All secrets inherit the same --ttl and --reads options.

sirr get

Retrieve and print a secret value. Each call increments the read counter. If the read limit is reached, the secret is burned immediately after being returned.

Usage

sirr get KEY

The value is printed to stdout with no trailing newline, making it safe to use in shell pipelines and variable assignments.

Example

sirr get DB_URL
# postgres://user:pass@db:5432/app

# Capture into a variable
export DB_URL="$(sirr get DB_URL)"

sirr pull

Pull all secrets from the server and write them to a .env file. If the file already exists, it is overwritten.

Usage

sirr pull .env

This is the inverse of sirr push .env. Use it to sync secrets to a new machine or restore a development environment.

Example

# On machine A
sirr push .env --ttl 24h

# On machine B
sirr pull .env
cat .env
# DB_URL=postgres://user:pass@db:5432/app
# API_KEY=sk-live-abc123

sirr pull reads every secret, so read counters will increment. If any secret has a read limit of 1, pulling will consume that read.

sirr run

Inject all secrets from the server as environment variables and execute a command. The secrets are never written to disk -- they exist only in the child process's environment.

Usage

sirr run -- <command> [args...]

The double dash -- separates Sirr's arguments from the command to run. Everything after -- is passed to the child process.

Example

# Run a Node.js app with all secrets injected
sirr run -- node app.js

# Run a Python script
sirr run -- python manage.py runserver

# Run any command
sirr run -- docker compose up

sirr list

List all secrets stored on the server. Shows metadata only -- keys, TTL, read counts, and creation timestamps. Secret values are never displayed.

Usage

sirr list

Example output

sirr list
# KEY         TTL        READS  CREATED
# DB_URL      58m left   0/1    2 min ago
# API_KEY     23h left   2/∞    1 hour ago
# REDIS_URL   6d left    0/∞    3 hours ago

sirr delete

Delete a specific secret immediately, regardless of its TTL or remaining reads.

Usage

sirr delete KEY

The secret is permanently destroyed from the server. This action cannot be undone.

Example

sirr delete DB_URL
# Deleted DB_URL

sirr prune

Delete all expired secrets from the server. Expired secrets are already unreadable, but pruning reclaims storage and cleans up the key list.

Usage

sirr prune

Example

sirr prune
# Pruned 12 expired secrets

Generate a shareable reference for a secret. The reference can be given to another person or system to retrieve the secret without exposing your master key.

Usage

sirr share KEY

Example

sirr share DB_URL
# https://your-sirr-server/s/a1b2c3d4e5f6

sirr audit

Query the audit log to see who accessed what and when.

Usage

sirr audit [options]

Name
--action
Type
string
Description
Filter by event type (e.g. secret.read, secret.created).
Name
--since
Type
duration
Description
Only show events after this duration ago (e.g. 1h, 7d).
Name
--limit
Type
number
Description
Maximum number of entries to show. Defaults to 50.

Example

# Last 20 read events
sirr audit --action secret.read --limit 20

# All events in the last 24 hours
sirr audit --since 24h

# Example output
# TIMESTAMP            ACTION          KEY
# 2025-02-27 14:30:00  secret.read     db/password
# 2025-02-27 14:28:00  secret.created  db/password

sirr keys

Manage scoped API keys for delegated access.

Usage

sirr keys list
sirr keys create --name NAME --perms PERMS [--prefix PREFIX]
sirr keys remove ID

Name
--name
Type
string
Description
Human-readable label for the key.
Name
--perms
Type
string
Description
Comma-separated permissions: read, write, delete, admin.
Name
--prefix
Type
string
Description
Optional key prefix restriction (e.g. ci/).

Example

# List all API keys
sirr keys list

# Create a read-only key for CI
sirr keys create --name "CI pipeline" --perms read,write --prefix ci/
# → Created key_a1b2c3d4
# → Token: sirr_sk_7f3a... (save this — shown only once)

# Revoke a key
sirr keys remove key_a1b2c3d4
# → Removed key_a1b2c3d4

TTL format

Sirr accepts human-readable duration strings for the --ttl flag. Combine a number with a unit suffix.

Format	Unit	Example
`30s`	seconds	30 seconds
`5m`	minutes	5 minutes
`2h`	hours	2 hours
`7d`	days	7 days
`30d`	days	30 days (max)

TTL examples

sirr push TOKEN=abc123 --ttl 30s        # Burns in 30 seconds
sirr push DB_URL=postgres://... --ttl 2h # Burns in 2 hours
sirr push .env --ttl 7d                  # All secrets burn in 7 days

If no --ttl is specified, the server's default TTL is used. Check your server configuration for the default value.