Local development

Day-to-day CLI workflow on your own machine: a default context per repository, one-off environment switches, worktrees, monorepos and local overrides.

This guide covers the everyday loop on a developer machine: pick a project and environment once per repository, run your app with varsafe run, and switch environments without surprises. It assumes the CLI is installed and signed in; if not, start with Getting started.

Set a default for the repository

From anywhere inside the repository, choose the project and environment:

varsafe use -p my-api -e development

Inside a git repository, this writes a .varsafe file at the repository root, even when you run it from a subdirectory. Run varsafe use with no flags at a terminal to pick from a list instead.

From then on, commands in that repository need no -p or -e:

varsafe run -- npm run dev

varsafe run prints the project and environment it used on stderr, for example Injecting 5 secrets from my-api/development, so a glance confirms where the values came from.

What .varsafe contains

The file holds the project, environment and team IDs, with their names as a comment. It contains no secret values:

{
  // my-api / development
  "projectId": "8d2f0c7e-3b1a-4c55-9e0f-2a6b1d4e7c90",
  "environmentId": "f41c9a22-6d0e-4b7f-8a13-5c2e9b0d6f18",
  "teamId": "0b7e5d31-9c4a-4f26-b8e1-7a3d2c6f5e04"
}

The CLI reads the IDs, not the comment, so renaming a project or environment does not break the file.

Commit it or ignore it

Either works. Decide per repository:

• Commit it when the team shares one default, usually development. Everyone who clones the repository starts in the same project. A teammate who runs varsafe use changes a tracked file, so their choice shows up as a diff. A teammate without access to that project is asked to pick another at a terminal; in a script, the command stops with Project not found. It may have been deleted. Run `varsafe use` to update.
• Ignore it when each developer chooses their own environment. Add .varsafe to .gitignore. A fresh clone then has no file and uses your user-level context until you run varsafe use.

If a .varsafe file names a team other than the project’s, the CLI rewrites it and says so (Updated /path/to/repo/.varsafe — it named a different team than my-api). Review that change before you commit it.

Outside a repository

Run varsafe use outside a git repository and the choice is saved for your user, in the CLI’s local store under ~/.varsafe. It applies wherever no .varsafe file is found: scratch directories, and repositories that do not have the file.

Clear it with:

varsafe use --clear

varsafe use --clear clears only the user-level context. To reset a repository, delete its .varsafe file.

How a command picks its project and environment

The first source that applies wins:

Flags replace the .varsafe file entirely, not field by field. See the next section for what that means in practice.

Use another environment for one command

Pass both the project and the environment:

varsafe run -p my-api -e staging -- npm run dev

Flags apply to that one command. They do not change the .varsafe file.

If you pass only one flag and the CLI has to ask you for the other, it saves your answer as your user-level context. That happens only on a machine with a stored sign-in; when VARSAFE_API_TOKEN is the only credential, nothing is saved.

Two terminals on different environments

Every terminal in a repository reads the same .varsafe file, so running varsafe use in one terminal changes what the next command in the other one uses. There are no environment variables that select a project or environment.

Keep the repository default for your main work, and pass flags in the other terminal:

varsafe run -- npm run dev

# Terminal 2: staging, whatever the repository default says
varsafe run -p my-api -e staging -- npm run dev

Git worktrees

Each worktree has its own root, so the CLI looks for .varsafe in the worktree you are in, not in the main checkout.

• If .varsafe is committed, every worktree gets the committed file. Running varsafe use in one worktree changes only that worktree’s copy.
• If .varsafe is ignored, a new worktree has none and uses your user-level context. Run varsafe use -p my-api -e development in the new worktree to give it its own default.

An ignored .varsafe is the simple way to keep worktrees on different environments: one per branch, each with its own file.

Monorepos

A repository has one git root, so varsafe use writes one .varsafe for the whole repository, wherever you run it.

When packages belong to different varsafe projects, put the flags in each package’s scripts instead of relying on the shared default:

{
  "scripts": {
    "dev": "varsafe run -p my-web -e development -- vite"
  }
}

The CLI looks for .varsafe from the current directory upwards and stops at the git root, and the nearest file wins. A .varsafe copied into a subdirectory therefore takes over for commands run there, and varsafe use does not update it, because use always writes the file at the root. If a package resolves to an unexpected project, look for a stray .varsafe between it and the root.

Local overrides

For settings that are not secrets and differ per developer, such as a local port or a feature flag, keep a plaintext .env.local out of git and load it inside the command, so its values win over the injected secrets:

varsafe run --shell 'set -a; . ./.env.local; set +a; exec npm run dev'

Keep secrets out of that file. For values that belong to an environment, use varsafe set instead.

--env-file is different: it accepts only an encrypted .env file, exported by varsafe, and merges it into the injected secrets:

varsafe run --env-file .env -- npm run dev

Check what the next command uses

varsafe status

varsafe status shows the credential in use, the context a command without flags would use (the .varsafe file if there is one, otherwise the user-level context), and how many secrets it holds. It never prompts and takes no -p or -e, so it answers “where will my next command go?” for the default case.

Next steps

• Move an existing .env into varsafe
• CLI reference: context
• Troubleshooting: the wrong project or environment
• CI/CD, where a pipeline passes -i and -e on every command