@kaundalvip/secureenv

Version control for your .env files, from the terminal.

Pull, push, diff and roll back environment variables the way you would code — including git-style conflict detection, so you never silently overwrite a teammate's change.

Official CLI for SecureEnv. Full documentation: https://www.secureenv.in/docs/cli

GitHub Actions

- uses: k-kaundal/secureenv@v1
  with:
    api-key: ${{ secrets.SECUREENV_API_KEY }}
    environment: production

- run: npm run build   # secrets are just there, and masked

See the Action docs.

Install

npm install -g @kaundalvip/secureenv

Requires Node.js 18 or later. The CLI targets https://www.secureenv.in by default — no --url needed.

Authenticate

Browser login (recommended)

secureenv login

This prints a browser URL and a code. Approve the request in your browser and the CLI receives an API key automatically.

Manual API key

Create a key in Settings → API Keys, then:

secureenv login --api-key <key>

Or use environment variables (useful for CI):

export SECUREENV_API_KEY=<key>
# only needed for self-hosted/dev instances:
export SECUREENV_URL=https://www.secureenv.in

Link a project

secureenv link              # interactive
secureenv link --project 1 --env 2

This creates .secureenv.json in the current directory. Add it to .gitignore.

Commands

secureenv login [--api-key <key>] [--url <url>]   # authenticate
secureenv logout                                  # remove saved API key
secureenv whoami                                  # current user
secureenv status                                  # auth + linked project

secureenv projects list                           # list accessible projects
secureenv envs list --project <id>                # list environments
secureenv envs create --project <id> --name prod  # create an environment
secureenv link [--project <id>] [--env <id>]      # link current directory
secureenv unlink                                  # remove local link

secureenv pull [--output .env]                    # download secrets to .env
secureenv push [--input .env] [--delete-missing] [--dry-run]  # upload .env
secureenv diff [--input .env]                     # compare local vs remote
secureenv run -- <command>                        # run with remote env vars
secureenv scan [--path <dir>] [--staged]          # find committed secrets
secureenv hooks install | uninstall               # pre-commit secret check
secureenv drift [--project <id>] [--strict]       # compare all environments
secureenv health [--project <id>] [--all]         # credentials overdue for rotation

secureenv history <KEY> [--reveal]                # who changed a value, and when
secureenv log <KEY>                               # alias for history
secureenv rollback <KEY> [--version <id>] [--yes] # restore an earlier value

All secret commands accept --project <id> and --env <id|name> (e.g. secureenv pull --project 1 --env prod) to target a specific environment without linking.

History and rollback

$ secureenv history DATABASE_URL

History for DATABASE_URL

* 412  Kamal  changed  yesterday
    ••••••••••••••••

| 388  Rahul  changed  3 days ago
    ••••••••••••••••

| 341  Kamal  created  12 days ago
    ••••••••••••

Values are masked. --reveal shows them, and each reveal is recorded in the audit log exactly like reading the current value.

secureenv rollback DATABASE_URL              # back to the previous value
secureenv rollback DATABASE_URL --version 388  # back to a specific one

A rollback is written as a new version rather than erasing the ones after it, so it can be undone the same way. How far back you can look depends on your plan's retention window; nothing outside it is deleted, and upgrading brings it back.

Environment drift

$ secureenv drift

KEY            development  staging  production  STATUS
----------------------------------------------------------
JWT_SECRET     A            A        —           MISSING
DATABASE_URL   A            A        B           differs

Letters mark distinct values: same letter, same value, — means not set. The values themselves are never sent to the client — the comparison happens server-side and only the verdict comes back.

Exits 1 when a key is missing from an environment, so it can gate a deploy:

secureenv drift || exit 1

A differing value does not fail by default, because a staging database URL is supposed to differ from production and a check that cries wolf gets deleted. --strict fails on those too.

Pre-commit hook

secureenv hooks install

Writes a pre-commit hook that runs secureenv scan --staged and blocks the commit if a staged file contains something shaped like a credential. Only staged files are scanned — checking the whole tree on every commit is slow and blocks you over findings you did not introduce.

If you already have a pre-commit hook, the check is appended rather than overwriting it. secureenv hooks uninstall removes only our block and leaves the rest alone.

Bypass a false positive with git commit --no-verify.

Concurrent edits

secureenv pull records the revision of every key in .secureenv.lock. push sends those revisions back, and the server rejects the push if a teammate changed a key since you pulled — the same way git rejects a non-fast-forward:

Push rejected — the environment changed since you pulled.

Pull again and retry, or --force to overwrite deliberately.

Push behavior

secureenv push uploads variables from your local .env to the linked environment. Use --dry-run to preview changes without writing, and --delete-missing to also remove remote variables that are absent locally (destructive — run a diff first).

Security

• Your API key is stored in ~/.secureenv/config.json with 0o600 permissions.
• Linked project config is stored in ./.secureenv.json with 0o600 permissions.
• Use scoped API keys with read/write permissions instead of sharing admin keys.