/vercel-env-push

The missing Vercel CLI command to push environment variables from .env files.

Primary LanguageTypeScriptMIT LicenseMIT

vercel-env-push 🔏

The missing vercel env push command

Screenshot of vercel-env-push

Integration Status License

Motivations

The Vercel command-line interface (CLI) provides a vercel env pull [file] command that can be used to pull development environment variables from a Vercel project and write them to a .env file. Unfortunately, the reverse operation is not doable through the Vercel CLI.

As I couldn't find any other tools providing this functionality with the features I wanted, I decided to write my own which internally uses npx to run the Vercel CLI either installed locally or fetched remotely.

Note On November 17th 2022, Vercel released bulk upload for environment variables altho this feature is only available through the Vercel Dashboard UI which is an improvement but still not ideal.

Features

  • Usable as a command-line tool or through an API
  • Push to multiple environments at once
  • Ability to add/remove/edit environment variables before pushing
  • Support for authorization tokens
  • Dry-run mode

Usage

CLI

You can either add vercel-env-push to your project and invoke it with your favorite package manager (or through an entry in your project's package.json file):

$ pnpm add -D vercel-env-push
$ pnpm vercel-env-push <file> <env> [...otherEnvs]

or use it directly with npx:

$ npx vercel-env-push <file> <env> [...otherEnvs]

The file argument is the path to the .env file containing the environment variables to push. The env argument is the name of the environment to push the environment variables to (the supported environments are development, preview and production). You can specify multiple environments by separating them with spaces.

Warning Due to the way the Vercel CLI works, if you have pre-existing environment variables associated to multiple environments (e.g. created through the Vercel Dashboard UI), running vercel-env-push to push environment variables to a single environment will remove the environment variables associated to the other environments. Note that environment variables pushed to multiple environments with vercel-env-push do not have this limitation as vercel-env-push will create a new environment variable for each environment instead of a single one shared across multiple environments.

Usage

# Push the environment variables from the .env.local file to the preview & production environments.
$ pnpm vercel-env-push .env.local preview production

Options

The following options are available through the CLI:

--dry, --dry-run

List environment variables without pushing them.

$ pnpm vercel-env-push .env.local development --dry
-t, --token

Login token to use for pushing environment variables.

$ VERCEL_ORG_ID=<ORG_ID> VERCEL_PROJECT_ID=<PROJECT_ID> pnpm vercel-env-push .env.local development -t <TOKEN>

This can be especially useful if you ever need to push environment variables from a CI pipeline.

- name: Push environment variables from GitHub Actions
  run: pnpm vercel-env-push .env.local preview -t "$VERCEL_TOKEN"
  env:
    VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
    VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
    VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
-b, --branch

The Git branch to apply the environment variables to when pushing environment variables to the Preview environment.

$ pnpm vercel-env-push .env.local preview --branch my-preview-branch

API

vercel-env-push can also be used through an API:

pushEnvVars(envFilePath: string, envs: string[], options?: Options): Promise<void>

Usage

import { pushEnvVars } from 'vercel-env-push'

// Push the environment variables from the .env.local file to the preview & production environments.
await pushEnvVars('.env.local', ['preview', 'production'])

Options

token

Determines a login token to use for pushing environment variables.

import { pushEnvVars } from 'vercel-env-push'

await pushEnvVars('.env.local', ['preview', 'production'], {
  token: process.env.VERCEL_TOKEN,
})
branch

Determines a Git branch to apply the environment variables to when pushing environment variables to the Preview environment.

import { pushEnvVars } from 'vercel-env-push'

await pushEnvVars('.env.local', ['preview'], {
  branch: process.env.GIT_BRANCH,
})
prePush

Specifies a callback that can be used to add/remove/edit environment variables before pushing.

import { pushEnvVars } from 'vercel-env-push'

await pushEnvVars('.env.local', ['preview', 'production'], {
  prePush: async ({ keyToRemove, ...otherEnvVars }) => {
    const secretValue = await getSecretValueFromVault()

    return {
      ...otherEnvVars,
      newKey: 'newValue',
      existingKey: 'updatedValue',
      secret: secretValue,
    }
  },
})

Note The dryRun & interactive options are also available through the API but are mostly useless in this context.

License

Licensed under the MIT License, Copyright © HiDeoo.

See LICENSE for more information.