stashbase.yaml

Custom config file allow you and your team to easily configure environments for various purposes or apps in your local development. Those files are in YAML format and be default they are named as stashbase.yaml but can be named any name you want.

Custom config files allow you to to easily pull environments and its secrets with a single CLI command just like you would pull git repositories. Those files can be stored in your git repository so whenever you pull or push changes every team member will be able to pull the environments and its secrets immediately.

Because the structure of those files serves as a blueprint you can use it to quickly create your own configs. These config gile are a powerful way to share your local development environments with your team members.

Structure

This is the structure of the config file. Each file is stored in YAML format. You can define multiple projects at the root of the file. Each project entry has the following properties:

project: the name or ID of the project
environment: the name or ID of the environment
description: the description of the environment (optional)
file: the global target local file
format: the global format of the file (optional, autodetected from the file extension); yaml, json or dotenv (default)
secrets: global secrets config details (optional)
pull: customize of the pull command (optional)
push: customize of the push command (optional)

Global secrets

only: array of names to select (optional)
exclude: array of names to exclude (optional)
set: object of name-value pairs to set (optional)
expand_refs: boolean (default: false), whether to expand references for pull or run commands (optional)
ignore-comments: boolean (default: false), whether to ignore comments (optional), for pull or push commands (optional)

Pull

file: file name to write the output to (optional), overrides the global file
format: the format of the file (optional, autodetected from the file extension); yaml, json or dotenv (default)

Secrets

print: boolean (optional), whether to print the secrets
set: object of name-value pairs to set (optional)
only: array of names to select (optional)
exclude: array of names to exclude (optional)
expand_refs: boolean (default: false), whether to expand references (optional)
ignore-comments: boolean (default: false), whether to ignore comments (optional)

Push

file: file name to read the input from (optional), overrides the globlal file
format: the format of the file (optional, autodetected from the file extension); yaml, json or dotenv (default)

Secrets

only: array of names to select (optional)
exclude: array of names to exclude (optional)
set: object of name-value pairs to set (optional)
ignore-comments: boolean (default: false), whether to ignore comments (optional)

Example

This is an example config file showcasing use of different properties.

- project: our-project
  environment: api_prod
  description: Produciton API server running on AWS
  push:
    # output format inferred from the extension
    file: .prod.env

- project: our-project
  environment: api_local
  file: .env.local
  pull:
    # overrides the global 'file'
    file: ../secrets.yaml
    secrets:
      ignore-comments: true
      expand-refs: true
      print: true
      only:
        - DATABASE_URL

- project: our-project
  environment: api_testing
  push:
    file: .env
  secrets:
    only:
      - DATABASE_URL
    set:
      - NODE_ENV: testing

Usage

Stashabse CLI can read this config file and pull all the environments and its secrets or you can run your commands using secrets from the config.

Run

If you want to run your command and inject secrets that were loaded from the config file use the stashbase run CLI command. Stashbase CLI will automatically search for stashbase.yaml file in the current directory.

If you use custom name you can pass it as an --file argument to the command. You can also pass the arguments like set or print for the secrets and it will be merged with the config file. If there are multiple entries in the config file like above, Stashbase CLI will propmpt you to select one.

You pass the command you want to run as value separated by double dashes --.

You can still use run command if you do not use config file, in that case you must provide the arguments directly to the command.

Examples

# auto detect config file in the current directory
stashbase run --set NODE_ENV=development -- bun run dev

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

# use without config file
stashbase run -p my-project -e api_local -- npm run start

Pull

You can easily pull the environments and its secrets using the stashbase pull CLI command. This command is similar to stashbase run but it will save the secrets to selected files. If there are multiple entries in the config file like above, Stashbase CLI will propmpt you to select one. The command will return error if there is not pull property in the selected entry.

As with the run command you can provide the arguments to override secrets config like exclude or change the output format directly in the pull command.

Examples

# auto detect config file in the current directory
stashbase pull

# provide custom config file path
stashbase pull --file my-file.yaml

# override some arguments
stashbase pull --exclude DATABASE_URL  --output .env.local --format dotenv

On this page