Free for now while in alpha pre-release-candidate phase

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 environment variables:

  • SIRR_SERVER -- the URL of your Sirr instance (default https://sirr.sirrlock.com). Zero-config cloud out of the box.
  • SIRR_TOKEN -- bearer token: your principal key (Cloud) or SIRR_MASTER_API_KEY value (self-hosted)
  • SIRR_ORG -- default organization ID for org-scoped commands

Environment setup — Cloud

export SIRR_TOKEN="your-principal-key"
export SIRR_ORG="your-org-id"

Environment setup — Self-Hosted

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

Use -v to print the CLI version.

sirr push

Push an anonymous (public) secret to the server. Accepts a raw value — no key name. The server generates a 256-bit hex ID and returns a shareable URL.

Usage

sirr push <VALUE> [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.

Dead drop a secret

sirr push "postgres://user:pass@db:5432/app" \
  --ttl 1h \
  --reads 1
# → id:  a3f8...7c2d
# → url: https://sirr.sirrlock.com/s/a3f8...7c2d

sirr push is for public dead drops — value-only, no key name. The returned URL can be shared with anyone. Use sirr set for org-scoped named secrets.

sirr set

Store a named secret in an organization scope. Requires --org (or $SIRR_ORG). Rejects duplicate keys with an error — delete the existing secret first.

Usage

sirr set KEY=VALUE --org <ORG> [options]
sirr set KEY -f <FILE> --org <ORG> [options]
  • Name
    --org
    Type
    string
    Description

    Organization ID. Can also be set via SIRR_ORG.

  • Name
    --ttl
    Type
    duration
    Description

    Time-to-live before the secret self-destructs.

  • Name
    --reads
    Type
    number
    Description

    Maximum number of reads before the secret is burned.

  • Name
    -f
    Type
    path
    Description

    Read the value from a file instead of inline.

Named secret

sirr set DB_URL="postgres://user:pass@db:5432/app" \
  --org org_a1b2c3d4 \
  --ttl 1h
# → key: DB_URL
# → id:  a3f8...7c2d

From file

sirr set TLS_CERT -f ./cert.pem --org org_a1b2c3d4

Duplicate key rejected

sirr set DB_URL="new-value" --org org_a1b2c3d4
# → Error: Key 'DB_URL' already exists. Delete it first.

sirr get

Retrieve and print a secret value. For public secrets, pass the hex ID. For org secrets, pass the key name with --org.

Usage

sirr get <ID>                    # public secret by hex ID
sirr get <KEY> --org <ORG>       # org secret by key name

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

Public secret by ID

sirr get a3f8...7c2d
# postgres://user:pass@db:5432/app

Org secret by key

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

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

sirr pull

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

Usage

sirr pull .env --org <ORG>

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

Example

sirr pull .env --org $SIRR_ORG
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 an org as environment variables and execute a command. The secrets are never written to disk -- they exist only in the child process's environment. Requires --org.

Usage

sirr run --org <ORG> -- <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 --org $SIRR_ORG -- node app.js

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

# Run any command
sirr run --org $SIRR_ORG -- 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. Requires --org.

Usage

sirr list --org <ORG>

Example output

sirr list --org $SIRR_ORG
# 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 <ID>                   # public secret by hex ID
sirr delete <KEY> --org <ORG>      # org secret by key name

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

Example

sirr delete DB_URL --org $SIRR_ORG
# 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 [--org ORG]

Pass --org to prune expired secrets within an org scope.

Example

sirr prune --org $SIRR_ORG
# Pruned 12 expired secrets

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
    --key
    Type
    string
    Description

    Filter by specific secret key or ID to trace a secret's lifecycle.

  • 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.

  • Name
    --org
    Type
    string
    Description

    Organization ID to query org-scoped audit logs.

Example

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

# Trace a specific secret's lifecycle
sirr audit --key DB_URL --org $SIRR_ORG

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

# 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

sirr orgs

Manage organizations. Requires master key authentication.

Usage

sirr orgs list
sirr orgs create NAME
sirr orgs delete ORG_ID

Example

# List all organizations
sirr orgs list
# ID              NAME        CREATED
# org_a1b2c3d4    acme-corp   2 days ago

# Create an organization
sirr orgs create acme-corp
# Created org_a1b2c3d4

# Delete an organization (must have no principals)
sirr orgs delete org_a1b2c3d4
# Deleted org_a1b2c3d4

sirr principals

Manage principals within an organization. Requires master key authentication.

Usage

sirr principals list --org ORG
sirr principals create --org ORG --name NAME --role ROLE
sirr principals delete --org ORG ID
  • Name
    --org
    Type
    string
    Description

    Organization ID to manage principals in.

  • Name
    --name
    Type
    string
    Description

    Human-readable name for the principal (required for create).

  • Name
    --role
    Type
    string
    Description

    Role to assign: reader, writer, admin, owner, or a custom role (required for create).

Example

# List principals in an org
sirr principals list --org org_a1b2c3d4
# ID              NAME      ROLE     CREATED
# prin_e5f6a7b8   ci-bot    writer   1 hour ago

# Create a principal
sirr principals create --org org_a1b2c3d4 \
  --name ci-bot --role writer
# Created prin_e5f6a7b8

# Delete a principal (must have no active keys)
sirr principals delete --org org_a1b2c3d4 prin_e5f6a7b8
# Deleted prin_e5f6a7b8

sirr roles

Manage roles within an organization. Requires master key authentication.

Usage

sirr roles list --org ORG
sirr roles create --org ORG --name NAME --perms PERMS
sirr roles delete --org ORG NAME
  • Name
    --org
    Type
    string
    Description

    Organization ID to manage roles in.

  • Name
    --name
    Type
    string
    Description

    Unique name for the custom role (required for create).

  • Name
    --perms
    Type
    string
    Description

    Permission letter string (required for create). Example: rRlL.

Example

# List all roles (built-in + custom)
sirr roles list --org org_a1b2c3d4
# NAME      PERMISSIONS      BUILTIN
# reader    rRl              yes
# writer    rRlLcCpP         yes
# admin     rRlLcCpPaAmM     yes
# owner     rRlLcCpPaAmMdD   yes
# auditor   rRlL             no

# Create a custom role
sirr roles create --org org_a1b2c3d4 \
  --name auditor --perms rRlL
# Created role auditor

# Delete a custom role
sirr roles delete --org org_a1b2c3d4 auditor
# Deleted role auditor

sirr me

View your connection info and principal identity. Works anonymously (shows connection info even without auth).

Usage

sirr me
sirr me keys
sirr me create-key --name NAME [--valid-after TS] [--valid-before TS]
sirr me delete-key KEY_ID
  • Name
    --name
    Type
    string
    Description

    Human-readable label for the new key (required for create-key).

  • Name
    --valid-after
    Type
    integer
    Description

    Unix timestamp after which the key becomes valid.

  • Name
    --valid-before
    Type
    integer
    Description

    Unix timestamp after which the key expires.

Example

# Show current identity (works even without auth)
sirr me
# Server:    https://sirr.sirrlock.com
# Principal: prin_e5f6a7b8 (ci-bot)
# Org:       org_a1b2c3d4
# Role:      writer
# Perms:     rRlLcCpP

# List your keys
sirr me keys
# ID              NAME          VALID
# key_c9d0e1f2    ci-deploy     active
# key_f3a4b5c6    temp-key      expired

# Create a new key
sirr me create-key --name deploy-v2
# Created key_g7h8i9j0
# Token: sirr_pk_9c4d... (save this — shown only once)

# Delete a key
sirr me delete-key key_f3a4b5c6
# Deleted key_f3a4b5c6

TTL format

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

FormatUnitExample
30sseconds30 seconds
5mminutes5 minutes
2hhours2 hours
7ddays7 days
30ddays30 days (max)

TTL examples

sirr push "abc123" --ttl 30s                              # Burns in 30 seconds
sirr push "postgres://..." --ttl 2h                       # Burns in 2 hours
sirr set DB_URL="postgres://..." --org $SIRR_ORG --ttl 7d # Burns in 7 days

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

Was this page helpful?