Environment Variables
biwa can forward local environment variables to the remote process (inheritance), send explicit values, and expand wildcard rules.
Config Keys
| Key | Type | Default | Description |
|---|---|---|---|
env.vars | array / table | [] | Environment variables to inherit, match, exclude, or set |
env.forward_method | string | "export" | Use "export" or "setenv" when sending variables |
Supported Config Forms
Array
[env]
vars = ["NODE_ENV", "API_KEY=secret", { DEBUG = "1" }]
forward_method = "export"Table
[env]
forward_method = "export"
[env.vars]
NODE_ENV = true
API_KEY = "secret"Array Of Inline Tables
[env]
vars = [{ NODE_ENV = "production" }, { API_KEY = "secret" }]NAMEorNAME = trueinherits the local value from your machine to the remote process.NAME=valueorNAME = "value"sends a literal value.
Wildcards And Negation
All env.vars forms (array, table, array of tables) support wildcard rules:
[env]
vars = ["NODE_*", "!*PATH"]*matches zero or more characters in an environment variable name.NODE_*inherits all local variables whose names start withNODE_.!*PATHremoves already-selected variables whose names end inPATH.- Prefer targeted patterns like
NODE_*,AWS_*, orCARGO_*. - Avoid mixing catch-all
*with explicit variable names in the sameenv.varssection; if you need broad matching, use specific prefixes plus exclusions instead.
Evaluation Order
Regardless of the config form or declaration order, rules are always evaluated deterministically:
- Inherit patterns — wildcard matches like
NODE_* = trueexpand first. - Exact specifications — explicit names like
NODE_ENV = trueorAPI_KEY = "secret"override inherited values. - Exclusions — removal rules like
!*PATH = trueapply last.
This means an explicit value always takes priority over a pattern-inherited one. For example, with NODE_* = true and NODE_ENV = "prod", even if the local machine has NODE_ENV = "dev", the result will be NODE_ENV = "prod".
BIWA_ENV_VARS
You can add environment variables from the local shell without touching config:
BIWA_ENV_VARS=NODE_ENV biwa run --skip-sync env
BIWA_ENV_VARS=NODE_ENV=prod biwa run --skip-sync env
BIWA_ENV_VARS=NODE_* biwa run --skip-sync envBIWA_ENV_VARS=NODE_ENVinherits a local value.BIWA_ENV_VARS=NODE_ENV=prodsets a literal value.BIWA_ENV_VARS=NODE_*uses wildcard inheritance.
biwa run --env
biwa run supports repeated flags, such as names, wildcards, and KEY=value pairs:
biwa run --env NODE_ENV --env API_KEY env
biwa run --env NODE_ENV=prod --env API_KEY env
biwa run --env NODE_* --env '!*PATH' envCLI --env values override config-defined env vars with the same name.
Forwarding Methods
exportprepends shell-safeexport KEY=VALUEstatements to the remote command. This is the default and most compatible mode.setenvuses SSHsetenvrequests before running the command.
UNSW CSE
UNSW CSE does not support SSH setenv, so use env.forward_method = "export" there.
mise Integration
Direct env forwarding sends values from your local machine. If the remote host should instead resolve tools and variables itself — from a project-local mise.toml / .tool-versions — enable the mise integration and biwa wraps each remote command with mise. The section is read only from global configuration or BIWA_MISE_* environment variables (see the warning below):
# ~/biwa.toml (global configuration only)
[mise]
enabled = true
mode = "exec"biwa run node --version
biwa run bun test
biwa run --env NODE_ENV=production npm run buildUse direct forwarding for values that only exist on your machine (secrets, CI tokens, per-run overrides), and mise for tool versions and project-wide variables that belong to the remote checkout.
Wrapping Order
Remote commands are always assembled in this order:
umask 077 && mkdir -p -- <remote dir> && cd <remote dir> && export NODE_ENV=production && mise exec -- npm run buildumaskfromssh.umask.mkdir -pandcdinto the remote project directory, so mise discovers the synced project'smise.toml.- Environment forwarding (
exportstatements, or SSHsetenvrequests before the command whenenv.forward_method = "setenv"). export MISE_ENV=<mise.env>, whenmise.envis set.- The mise wrapper.
- Your command with shell-quoted arguments.
Forwarded variables are therefore visible to mise itself and are inherited by the command it runs; explicit mise.toml values win over the forwarded ones inside the mise environment.
Modes
exec(default) — prefixes the command with<mise.bin> exec --.prefix— prefixes the command withmise.command_prefixverbatim. Settingcommand_prefixalso overrides the prefix inexecmode, so it works as a general escape hatch:toml# ~/biwa.toml (global configuration only) [mise] enabled = true command_prefix = "mise x --"mode = "prefix"without acommand_prefixis a configuration error.
The [mise] section is global-only
Every key in [mise] helps choose the program that wraps your remote commands. command_prefix is inserted without shell quoting, and enabled plus bin are enough on their own: bin = "sh" turns the wrapper into sh exec -- …, which runs a file named exec from the synced project. Since biwa discovers config files by walking up from the current directory, a biwa.toml committed to a cloned repository could otherwise pick what runs on your SSH host.
biwa therefore reads the whole [mise] section only from global configuration (~/biwa.toml, ~/.biwa.<ext>, $XDG_CONFIG_HOME/biwa/config.<ext>) or BIWA_MISE_* environment variables. A project-local config that sets any [mise] key is rejected with an error naming the offending keys, the same way [direct] settings are limited to global configuration.
The wrapper prefixes the whole command, exactly like running env or nice in front of it, so shell operators inside a command string (|, &&, redirects) still bind in the remote shell rather than inside mise. In other words, biwa run 'a && b' runs only a under mise; wrap compound commands yourself to run all of them inside the environment:
biwa run sh -c 'a && b'Shell activation
mode = "activate" (eval "$(mise activate ...)") is not implemented. Remote commands run through a non-interactive shell where activation hooks do not fire reliably; exec provides the same tool and environment resolution without depending on shell integration.
Remote Setup
mise has to exist on the remote host. Bootstrap it once with the integration turned off, so the bootstrap command itself is neither blocked by the availability check nor wrapped by the missing wrapper:
BIWA_MISE_ENABLED=false biwa run --skip-sync 'curl https://mise.run | sh'
BIWA_MISE_ENABLED=false biwa run --skip-sync 'mise --version'Before wrapping a command, biwa checks that the configured wrapper exists remotely and fails with setup instructions when it does not. The check follows the configuration: it looks up mise.bin in exec mode, and the first word of mise.command_prefix when a prefix is configured, so an unused bin never causes a false failure. If the remote installation is not on the non-interactive PATH, set bin to its absolute path (for example bin = "~/.local/bin/mise"); bin must be a bare command name, an absolute path, or a ~-relative path. Set verify = false to skip the extra check and its round trip.
Environment-Dependent Variables
biwa warns when you inherit machine-specific variables such as:
PATH,LD_LIBRARY_PATH,LIBRARY_PATHHOME,PWD,OLDPWDPYTHONHOME,PYTHONPATH,VIRTUAL_ENV,CONDA_PREFIXNODE_PATH,NPM_CONFIG_PREFIXJAVA_HOME,CLASSPATHGOPATH,GOBIN,GOMODCACHEGEM_HOME,GEM_PATH,BUNDLE_PATH,BUNDLE_BINCARGO_HOME,RUSTUP_HOMEPHP_INI_SCAN_DIR
Those values often differ between your local machine and the remote host.
Security
Inherited variables are injected into the remote process environment. Be careful when sending secrets, and prefer only the variables you actually need.