Run

stashbase run loads secrets from Stashbase or a local file, then injects them into the spawned child process's environment. The secrets exist only for that process's lifetime; they are not exported into your current shell.

Quick start

stashbase run -- npm run dev

Stashbase looks for stashbase.yaml in the current directory, loads the configured secrets, and starts npm run dev as a child process with those secrets available to it.

How it works

Current shell
    │
    ▼
stashbase run
    │
    ▼
Spawn child process
    │
    ▼
Inject secrets
    │
    ▼
Run command

The executed command receives the secrets through its process environment. When the command exits, its child process exits too, and the injected environment disappears with it.

Process-scoped secrets

stashbase run does not export secrets into the parent shell. They are available only inside the command it runs.

stashbase run -- npm run dev

echo $DATABASE_URL
# empty

For example, npm run dev can read DATABASE_URL, but the echo command in your original shell cannot.

Loading secrets

You can load secrets through a config file, a local file, or direct CLI arguments.

Config file

By default, Stashbase searches for stashbase.yaml in the current directory. A config file is useful for repeatable local workflows and can contain more than one project or environment entry. If there are multiple entries, Stashbase prompts you to select one.

# Automatically detect stashbase.yaml in the current directory
npx stashbase run -- npm run dev

# Provide a custom config file path
stashbase run --config-file my-file.yaml -- bun run dev

You can pass secret options such as --set or --print-secrets; they are merged with the selected config entry.

Local file

Use --file to load secrets from a local file instead of Stashbase. Local secret files can be in .env, YAML, or JSON format.

stashbase run --file .env.production -- npm run dev

CLI arguments

You can use the run command without a config file. Provide the project and environment directly, then add secret options as needed.

stashbase run -p our-project -e api_local -- npm run dev

# Add secret-loading options
stashbase run -p our-project -e api_local \
  --only DATABASE_URL \
  --exclude DATABASE_PASSWORD \
  -- npm run dev

Load only the required secrets

Use --only when the command needs a small, known set of secrets. This reduces the number of secrets available to the executed command.

stashbase run \
  -p booking-app \
  -e production \
  --only DATABASE_URL \
  -- npm run dev

--only accepts a comma-separated list of secret names. You can also use it in a config file.

AI-assisted development

run can fit AI-assisted development workflows because it injects only the secrets you select into the executed command instead of exporting an entire .env file into the shell.

stashbase run \
  --only GH_TOKEN \
  -- gh workflow run deploy.yml

This command makes GH_TOKEN available to gh for that process invocation.

Examples

The following stashbase.yaml defines two reusable entries, including secret filters and overrides:

- project: our-project
  environment: api_local
  description: Used only for database migrations
  secrets:
    expand-refs: true
    only:
      - DATABASE_URL

- project: our-project
  environment: api_testing
  description: Run against database in test environment
  pull:
    output: .prod.env
    format: dotenv
  secrets:
    only:
      - DATABASE_HOST
      - DATABASE_PORT
      - DATABASE_PASSWORD
    set:
      - NODE_ENV: production

Run a command with a selected config entry, or use direct arguments and secret filters:

# Stashbase prompts for an entry when the config file has multiple entries.
stashbase run -- npm run dev

# Run without a config file and override the loaded secrets.
stashbase run -p our-project -e api_local \
  --only DATABASE_URL \
  --exclude DATABASE_PASSWORD \
  -- npm run dev

Options reference

stashbase run [OPTIONS] [COMMAND]...