Wrap a Build

envless build decrypts your variables and launches a build command with them set in the environment. It is envless run with a label on it: same resolution, same injection, same exit code, plus an optional target name so your logs say which build the variables went into. No files are written, no imports added, and the values disappear when the command exits.

Basic usage#

envless build -- vite build
envless build -- npm run build
envless build web -- next build

Everything after -- is the command and its arguments. Envless resolves the target, decrypts the bundle, spawns the command with the values in its environment, forwards SIGINT and SIGTERM, and exits with the child's exit code.

The target label#

envless build web -- vite build
envless build cloudflare -- wrangler deploy

The optional positional between build and -- is a label and nothing else. It appears in the spinner and in the success line, and it changes nothing about what gets injected. It does not select a product, a project, or an environment, so use --env for that. If several positionals appear before --, the first is the label and the rest are ignored.

✔ 12 variables from Production → building web → vite

Anything after -- belongs to the child, flags included, so envless build -- vite build --mode production hands --mode production to vite untouched. Every Envless flag goes before the --.

Picking an environment#

envless build --env production -- vite build
envless build web --env staging,production -- npm run build

--env takes a comma separated list. Environments are merged left to right, so a name defined in production overwrites the same name from staging.

When neither --env nor ENVLESS_ENV is set and .envless lists more than one environment, build warns and takes the first: Multiple environments linked, using development. Pass --env to choose. A list you pass explicitly is never truncated that way.

Every flag#

build has four flags of its own. Each one resolves flag first, then the environment variable, then the .envless file:

If --workspace (device login only), --project or --env is still missing after all three sources, the command names the ones it is missing and exits 1 without contacting the API.

Credentials never come from a flag. ENVLESS_TOKEN carries the token, then ENVLESS_KEY or ENVLESS_PASSPHRASE carries the decryption key. A .env file in the working directory can supply the ENVLESS_* names too, except ENVLESS_TOKEN, ENVLESS_KEY and ENVLESS_PASSPHRASE, which the CLI refuses to read from a file, and a value already set in your shell always wins over the file.

The environment the child receives#

The child inherits the parent's full environment (HOME, PATH, and everything else pass straight through), then the decrypted values are layered on top, so an Envless value overrides a same-named ambient one. The merge is { ...process.env, ...safeValues }, where safeValues is the decrypted set minus the refused names below. A config file that reads process.env at build time, like vite.config.ts or next.config.js, sees the values with no change to the config.

Injecting a value into the build process is not the same as shipping it. Whether a name ends up inside your bundle is decided by your bundler's inlining rules, and anything inlined into a client chunk is public. See Server vs client and the framework pages for where that line sits.

Names that are never injected#

A decrypted variable whose name changes how a process or its children execute code is never placed in the child environment, because storing one would turn write access to a variable into code execution. envless build drops the value and prints a warning. Any ambient value survives untouched, so refusing a stored PATH cannot break the build.

Twenty-six names are refused:

The warning names every value that was dropped:

⚠ [envless] These variables were decrypted but not written into the process environment, because their names change how this process or its children execute code, so storing one turns write access to a variable into code execution: NODE_OPTIONS

In package.json#

Wrap the build script so nobody has to remember the prefix:

{
    "scripts": {
        "build": "envless build -- vite build",
        "build:staging": "envless build web --env staging -- vite build",
        "deploy": "envless build cloudflare --env production -- wrangler deploy"
    }
}

When to pick build over the other modes#

CI / production#

The same command works non-interactively. Swap the cached login for a machine key and provide the decryption key:

export ENVLESS_TOKEN=ev_sk_xxxxxxxxxxxx    # machine key, dashboard → Keys
export ENVLESS_KEY=xxxxxxxxxxxx            # workspace key, Settings → CI / Machine Access

envless build web --project billing-api --env production -- npm run build

The ev_sk_ token scopes the workspace, so --workspace isn't required. You only need --project and --env (or a .envless file), and both also read ENVLESS_PROJECT and ENVLESS_ENV. Use ENVLESS_PASSPHRASE instead of ENVLESS_KEY if you'd rather derive the key from the passphrase. See CI/CD & Production for full setups.

What it does under the hood#

Errors#

Notes#

• Variables are never written to disk. build does not read or write the on-disk cache that @goenvless/env keeps and envless cache clear wipes.
• The child sees the values through standard process.env, except for the refused names above.
• A variable with no value is skipped with Variable <name> has no value, skipping it., and the build still runs.
• build reads but never writes: an ev_sk_ machine key is enough, and nothing in your workspace changes.
• envless build --help prints the build section of the CLI help. A --help placed after the -- goes to the child, as any other flag does.