Installation

Install the enveil CLI and sign in

Install the CLI

The installer downloads a prebuilt enveil binary for macOS or Linux (x86_64 and arm64) and puts it in ~/.cargo/bin:

sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/hauju/enveil/releases/latest/download/enveil-cli-installer.sh | sh

From a checkout of the repository, build it with Cargo instead:

sh
cargo install --path crates/enveil-cli

Check it runs:

sh
enveil --version

Shell completions

enveil completions <shell> prints a completion script for bash, zsh, fish, elvish or powershell:

sh
enveil completions fish > ~/.config/fish/completions/enveil.fish
enveil completions zsh > ~/.zfunc/_enveil      # a directory on your $fpath

Point it at a server

Every command needs to know which enveil deployment to talk to. Set ENVEIL_SERVER once, and login, logout, projects and init use it from any directory:

sh
export ENVEIL_SERVER=https://enveil.oxidt.com      # bash, zsh
set -Ux ENVEIL_SERVER https://enveil.oxidt.com     # fish

Inside a project, the server in its .enveil.toml wins over ENVEIL_SERVER, so a project pinned to another deployment stays pointed at it. --server <url> on the command line wins over both. See Projects and environments.

Sign in

With a browser

sh
enveil login

This opens the enveil sign-in page in your browser, and prints the link in case it does not open. After you sign in, you choose which organization the CLI may act in, and the browser hands the token back to the CLI on a 127.0.0.1 port.

Without a local browser

On an SSH session, a VPS or a cloud agent's sandbox, no browser can reach the CLI's loopback port. Use the device flow:

sh
enveil login --device
text
To sign in, open https://enveil.oxidt.com/device in any browser and enter the code

  BCDF-GHJK

Or open https://enveil.oxidt.com/device?user_code=BCDF-GHJK

Waiting for approval…

Open the link on any machine, sign in, pick the organization and approve. The CLI polls until you do, then stores the token as login would. If the code expires first, run the command again.

Where the token lives

What Detail
Storage The OS keychain (the macOS Keychain, or the Secret Service on Linux), one entry per server URL
On disk or in the environment Never. A child process cannot inherit it by accident
Lifetime Renews itself while the CLI is used. A login left unused for 90 days ends, and enveil login is needed again
Scope One organization, the one picked when signing in

To work in a different organization on the same server, enveil logout, then enveil login and pick the other one.

Which credential a command uses

Order Source Renews
1 ENVEIL_TOKEN, usually a machine identity (evl_…) No
2 The keychain entry from enveil login for this server Yes
3 Inside GitHub Actions with id-token: write: a short-lived identity exchanged for the run's OIDC token No

ENVEIL_TOKEN wins, so a script or agent given a machine identity acts as that identity even on a machine where someone is signed in. See CI with GitHub Actions for the third case.

enveil whoami shows which identity the current credential is, with its scopes, expiry and read limits.

Sign out

sh
enveil logout

This revokes the session on the server, then removes the token from the keychain. If the server cannot be reached, the token is removed anyway and the session expires on its own.