dniccum/secret-stash-cli

A PHP-based Composer package to interact with the SecretStash environment variable service.

v0.3.0 2026-03-05 04:04 UTC

Requires

• php: ^8.2
• endroid/qr-code: ^5.0.9
• guzzlehttp/guzzle: ^7.10
• illuminate/console: ^11.0|^12.0
• illuminate/contracts: ^11.0||^12.0
• illuminate/support: ^11.0|^12.0
• laravel/prompts: ^0.3.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/boost: ^2.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^10.0.0||^9.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• spatie/laravel-ray: ^1.35

MIT

• Doug Niccum

• laravel
• environment
• variables
• dniccum
• secret-stash
• secret-stash-cli

README

A beautiful Laravel Composer package that provides Artisan commands for interacting with the SecretStash REST API. Manage your organizations, applications, environments, and variables directly from the command line with an intuitive, interactive interface.

Table of Contents

• Features
• Requirements
• Installation
  • API Key
  • Application Id
• Configuration
• Usage
  • Managing Variables
    • Pulling Variables (secret-stash:variables pull)
    • Pushing Variables (secret-stash:variables push)
    • Listing Variables (secret-stash:variables list)
  • Managing Environments
    • List Environments (secret-stash:environments list)
    • Create Environment (secret-stash:environments create)
    • Share Environment (secret-stash:share)
  • Managing Encryption Keys
    • Generate a Key (secret-stash:keys generate)
    • Set an Existing Key (secret-stash:keys set)
    • List Keys (secret-stash:keys list)
    • Device Status (secret-stash:keys status)
    • Initialize Device (secret-stash:keys init)
    • Sync Device (secret-stash:keys sync)
    • Key Recovery (secret-stash:keys recovery)
  • Managing Envelopes
    • Rewrap Envelope (secret-stash:envelope rewrap)
    • Repair Envelope (secret-stash:envelope repair)
    • Reset Envelope (secret-stash:envelope reset)
• Changelog
• Contributing
• Credits
• License

Features

• 🎨 Beautiful Console Interface - Built with Laravel Prompts for an interactive, user-friendly experience
• 🔐 Secure API Authentication - Uses Laravel Sanctum tokens for secure API access
• 🚀 Easy Installation - Simple Composer installation with Laravel auto-discovery
• 💾 Environment File Sync - Pull and push variables to/from .env files
• ✨ Interactive Prompts - Smart prompts guide you through each operation

Requirements

• PHP 8.2 or higher
• Laravel 11 or higher
• A SecretStash API Key

Installation

You can install the package via Composer:

composer require dniccum/secret-stash-cli

Execute the installation command. This will optionally publish the configuration file and create an environment key used to encrypt your variables before they are sent to SecretStash's servers:

php artisan secret-stash:install

Important

This package creates a ~/.secret-stash directory on your machine. Ensure this folder is secure as it contains the keys required to decrypt your environment variables.

API Key

Within the SecretStash application interface, go to your user's profile settings, and access the "Tokens" tab. Provide a unique name for a token and then click "Create." Copy the provided token and set it as the SECRET_STASH_API_KEY environment variable in your .env file:

SECRET_STASH_API_KEY=your_token_here

Application ID

If you have not already, create a new application within SecretStash. You can do this by navigating to the "Dashboard" page in the SecretStash application interface and click "New application." Provide a name for your application and click "Create." Copy the provided application ID and set it as the SECRET_STASH_APPLICATION_ID environment variable in your .env file:

SECRET_STASH_APPLICATION_ID=your_application_id_here

Note

The SecretStash CLI requires both the API key and Application ID to be present to work. Failure to set them will throw an error.

Configuration

If you have not already, publish the configuration file using php artisan vendor:publish --tag=secret-stash-config. This will create a config/secret-stash.php file where you can customize the package's behavior.

Ignored Variables

In the event that you do want SecretStash to make a record of variables, you can define them within the secret-stash.ignored_variables section of the config/secret-stash.php file. This is useful for variables that are dynamically generated, specific to your environment, or should not be stored in SecretStash.

Example

The example below would not sync (pull or push) the DB_DATABASE or DB_USERNAME variables to the target .env file.

return [
    'ignored_variables' => [
        'DB_DATABASE',
        'DB_USERNAME',
        // Add more variables as needed
    ],
];

Note

The secret-stash:variables push command automatically ignores variables starting with SECRET_STASH_ to prevent circular configuration issues.

Usage

SecretStash CLI provides a set of Artisan commands to interact with your SecretStash application. Most commands are interactive, but they also support options for CI/CD environments.

Managing Variables

The primary purpose of this package is to sync your local .env file with the SecretStash API.

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

Options:

• --application: The unique application ID that identifies your application within SecretStash
• --environment: Specify the environment slug (e.g., production). Defaults to the environment that is set in your APP_ENV definition.
• --file: The path to the file you want to update (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

Note: By default, any variable starting with SECRET_STASH_ or defined in the ignored_variables config array will be skipped to prevent circular dependencies.

Options:

• --application: The unique application ID that identifies your application within SecretStash
• --environment: Specify the destination environment. If the environment doesn't exist, you will be prompted to create it.
• --file: The source file to read (defaults to .env).

Listing Variables

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

php artisan secret-stash:variables list

Managing Environments

Environments allow you to group variables by stage (e.g., staging, production).

List Environments

View all environments associated with your application:

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

Create Environment

Create a new environment for your application:

php artisan secret-stash:environments create

Options:

• --application: The unique application ID that identifies your application within SecretStash
• --name: The name of the environment (e.g., Staging).
• --slug: The environment slug (e.g., staging).
• --type: The environment type (local, development, or production).

Share Environment

To share an environment with other team members, use the share command. This will identify which team members do not have access and create the necessary encryption envelopes for them:

php artisan secret-stash:share

Options:

• --application: The unique application ID that identifies your application within SecretStash
• --environment: Specify the environment slug (e.g., production). Defaults to the environment that is set in your APP_ENV definition.

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.

Important

This portion of the package is something that you will likely not need. Please be sure to perform the installation command php artisan secret-stash:install. This will generate the necessary encryption keys for you.

Generate a Key

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

php artisan secret-stash:keys generate --environment=production

Set an Existing Key

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

php artisan secret-stash:keys set --environment=production --key=your-base64-encoded-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).

Testing

Use Composer:

composer test

or Pest:

./vendor/bin/pest

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• Doug Niccum
• All Contributors

License

The MIT License (MIT). Please see License File for more information.