CLI guide

The CLI puts the right .env on any machine and lets you review history, manage environments and create tokens without opening the browser. Install it with the installation guide, or in one line as shown below.

Install and update#

$npm install -g @secretvariable/cli$svar --version

The package needs Node.js 20 or newer, is a single file with no dependencies, and works on any system where Node.js runs. Update with npm update -g @secretvariable/cli and remove with npm uninstall -g @secretvariable/cli. If your shell cannot find svar, add the folder printed by npm config get prefix (its bin subfolder) to your PATH. The installation guide also shows how to build the CLI from source.

The svar command#

Installing the CLI gives you two names for the same program: svar (short, used throughout these guides) and secretvariable. Hints and errors print the name you typed. The short name is not sv because that is already the Svelte CLI and, on many Linux systems, the runit sv command.

Sign in#

$svar login --server https://secrets.example.com

You are asked for your email and password (or pass --email and --password). The password is exchanged for a 90-day personal token and is never stored. Credentials live in ~/.config/secretvariable/config.json with mode 0600. svar login --token <token> signs in with an existing token. svar logout forgets the local credentials; revoke the token itself in the web app (Account) or with svar token revoke <id>.

With two-step verification#

If your account uses two-step verification you are asked for a code after the password. Type the authenticator code, email to get a one-time code by email, or recovery to use a recovery code. Without a terminal, pass it as a flag:

$svar login --server https://secrets.example.com --code 123456$svar login --server https://secrets.example.com --method recovery --code abcde-fghij

Emailed codes need an interactive terminal.

Link a folder to a project#

$svar init                                    # choose interactively$svar init --org acme --project payments-api  # no prompts$svar init --create --project "New app"       # create it first

This writes .secretvariable.json: the project id and the current environment. It contains no secrets and is safe to commit. The CLI finds it in the current folder or any parent.

pull, push, status and run#

$svar push -m "rotate Stripe key"$svar run --env production -- npm start

History#

$svar log                  # versions of the current environment$svar diff 3 4             # key names only$svar diff 3 4 --reveal    # with values (recorded in the audit log)$svar rollback 3           # saves v3's content as a new version

Rolling back never rewrites history: it creates a new version with the old content.

Environments#

$svar env list$svar env use staging$svar env create preview --from production        # copy from the current version$svar env create preview --from production@4      # copy from v4

Team and tokens#

$svar invite dana@example.com --role viewer --envs staging --expires 3$svar invite dana@example.com --role editor --send-email$svar accept <invite-token>$svar members$svar token create --name ci --env production --access read --expires 90$svar token list$svar token revoke <id>

--expires sets the invitation lifetime in days (1 to 30, default 7). --send-email also emails the link to the invitee; it needs SMTP configured on the server and otherwise fails with a clear message without creating the invitation. If the mail server fails, the invitation is still created and the command prints the link so you can share it by hand. Tokens created inside a project folder are service tokens limited to that project; add --env to limit one environment and --access read to make them read-only.

Using it in CI#

Create a read-only service token for one environment and store it as a CI secret. Provide the server URL and token as environment variables, and run pull or run:

- run: svar pull --force  env:    SECRETVARIABLE_URL: ${{ secrets.SV_URL }}    SECRETVARIABLE_TOKEN: ${{ secrets.SV_TOKEN }}

The repository needs its .secretvariable.json checked in (it only holds ids), or run svar init first. Install the CLI in the job the same way as locally; once it is published you will be able to use npx -p @secretvariable/cli svar pull.

Configuration#

Commands that fail exit with a non-zero status and print what went wrong and how to recover. Next: the web app guide.