Available commands

Introduction

The SecretStash CLI lets you securely create and manage environment variables across multiple applications. It syncs your application's .env with SecretStash, and most commands are interactive but also provide flags for automation.

Managing Variables

Listing variables

To see a summary of the variables currently stored in SecretStash for your environment:

php artisan secret-stash:variables list [--environment=<slug>]

Options

• --environment defaults to APP_ENV if omitted

Pulling variables

The pull command retrieves variables from SecretStash, decrypts them using your local environment key, and updates your local .env file.

php artisan secret-stash:variables pull [--environment=<slug>] [--file=<path>] [--key=<key>]

Options

• --environment defaults to APP_ENV if omitted
• --file defaults to .env

Pushing variables

The push command reads your local .env file, encrypts the values, and sends them to the SecretStash API.

php artisan secret-stash:variables push

Notes:

• Variables starting with SECRET_STASH_ are ignored automatically.
• You can also ignore specific variables in config/secret-stash.php.

Managing Environments

List environments

Shows all environments in SecretStash, including each environment's:

• ID
• name
• environment type
• slug
• created date

php artisan secret-stash:environments list
# or using the alias
php artisan secret-stash:env

Create an environment

Creates a new environment in the SecretStash service.

php artisan secret-stash:environments create [--name=<name>] [--slug=<slug>] [--type=<local|development|production>]

Options

• --name the name of the environment (e.g., Staging).
• --slug a shortened, url-friendly version of the environment name (e.g., staging). This will need to match the APP_ENV environment variable.
• --type the type of environment, allowing to easily identify which environments are which within the SecretStash service. Available options are:
  • local
  • development
  • production

Managing Encryption Keys

SecretStash CLI uses client-side encryption. This means your raw values never touch SecretStash's servers; only the encrypted payloads do. Keys are stored locally in ~/.secret-stash.

Generate a Key

Generate a new 32-byte encryption key for an environment:

php artisan secret-stash:keys generate [--environment=<environment>]

Set an Existing Key

If you are setting up a new machine and already have a key:

php artisan secret-stash:keys set [--environment=<environment>] [--key=<key>]

Options

• --environment: Specify the environment slug (e.g., production).
• --key: The Base64-encoded encryption key.

List Keys

View which environments have keys configured on your local machine:

php artisan secret-stash:keys list

Device Status

View the status of your local private key and server registration:

php artisan secret-stash:keys status

Initialize Device

Generate and register a new RSA-4096 key pair for this device:

php artisan secret-stash:keys init

Options

• --force: Force device key regeneration.
• --label: Provide a custom label for this device (e.g., "Work MacBook").

Sync Device

Sync your local device metadata from the SecretStash server:

php artisan secret-stash:keys sync

Key Recovery

Generate a recovery key and export it to a file or QR code:

php artisan secret-stash:keys recovery

Options

• --copies: Number of recovery share copies to print.
• --output-dir: Directory to save recovery share files.

Managing Envelopes

Managing envelopes is critical to SecretStash's client-side encryption model. Your raw environment variables are never stored on our servers; instead, they are encrypted using an environment-specific Data Encryption Key (DEK).

To share this DEK securely, SecretStash uses "envelopes"—the DEK encrypted with a user's unique RSA public key. Only the intended recipient, using their local private key, can "open" the envelope to retrieve the DEK and decrypt the variables.

Rewrap Envelope

When to use: Use this when moving to a new machine or generating a new device key pair while still having access to your old private key.

Why it's important: It migrates access to your new device. It uses your old private key to decrypt the DEK and immediately re-encrypts it with your new public key, creating a new envelope for your current session.

php artisan secret-stash:envelope rewrap

Options

• --application: The unique application ID that identifies your application within SecretStash
• --environment: Specify the environment slug (e.g., production).
• --old-key-file: Path to your old private key PEM file.
• --old-device-key-id: The ID of your old device key.

Repair Envelope

When to use: Use this if you encounter decryption errors or "envelope not found" messages after a device change or key sync issue.

Why it's important: It simplifies recovery by first attempting a rewrap with your old credentials. If that fails, it provides a fallback option to reset the environment envelopes entirely.

php artisan secret-stash:envelope repair

Options

• --application: The unique application ID that identifies your application within SecretStash
• --environment: Specify the environment slug (e.g., production).
• --old-key-file: Path to your old private key PEM file.
• --old-device-key-id: The ID of your old device key.

Reset Envelope

When to use: Use this "break glass" operation if keys are lost, a device is compromised, or during a scheduled security rotation.

Why it's important: It generates a brand-new DEK and creates new envelopes for all registered devices.

!WARNING This is a destructive action. Once reset, all team members must pull the latest variables and re-push them to ensure they are encrypted with the new key. Any variables not re-pushed will be inaccessible.

php artisan secret-stash:envelope reset

Options

• --application: The unique application ID that identifies your application within SecretStash
• --environment: Specify the environment slug (e.g., production).

Tips

• Run php artisan --help | grep secret-stash to discover all commands.
• In CI, provide SECRET_STASH_API_KEY and SECRET_STASH_APPLICATION_ID via secrets.