CLI reference
The veil CLI is a single binary that brings Veil Keys’ “use, never read” guarantee to your local shell and CI pipelines. It resolves secrets at the moment a command runs, hands them to that one process, and never writes them to disk. There are two commands: veil run for injecting secrets into a child process, and veil ssh-agent for brokering SSH signing.
Install
One line on macOS or Linux — downloads the right prebuilt binary for your OS/arch:
On Windows, download veil-windows-x64.exe from the releases page. Then get your tokens from the app under Agents & Security → Developer CLI.
Authentication
The CLI authenticates with scoped tokens passed through environment variables. Each command uses its own token kind — they are not interchangeable.
| Command | Token env var | Token kind |
|---|---|---|
veil run | VEIL_TOKEN | CI token (veil_ci_…) |
veil ssh-agent | VEIL_SSH_TOKEN | SSH token (veil_ssh_…) |
VEIL_API is an optional override for the API endpoint; you normally don’t need to set it. See Tokens for how to mint each kind.
veil run
Resolves secrets from a manifest, injects them as environment variables into the child process only, masks them in the child’s output, and never persists them.
Flags and arguments
| Flag / arg | Meaning |
|---|---|
-f <manifest> | Path to the manifest file. Defaults to .veil.json in the current directory. |
--print | Show a masked preview of what would be injected, without running the command. |
-- <command…> | Everything after -- is the command to run with secrets injected. |
The manifest (.veil.json)
The manifest maps environment variable names to Veil services. A bare service name resolves that service’s primary secret; service/field selects a specific field.
{
"STRIPE_API_KEY": "stripe",
"DATABASE_URL": "primary-db/dsn",
"OPENAI_API_KEY": "openai"
}At run time, Veil resolves each entry, sets the variables for the child process, and runs your command. If any secret fails to resolve, veil run aborts before the command starts — your command never runs with a half-populated environment.
Masked output
Secret values are masked in the child process’s stdout and stderr, so a value that accidentally gets echoed shows as ████ rather than leaking into your CI logs.
Preview with --print
Use --print to verify a manifest in CI setup without running anything. It lists the variables that would be set, with values masked.
veil ssh-agent
Runs a local SSH agent that brokers signing to Veil. Your SSH private keys stay sealed in Veil; the agent only asks Veil to sign authentication challenges, so standard tools like ssh and git work unchanged.
| Flag | Meaning |
|---|---|
-S <socket> | Path for the agent’s listening socket. Optional; a default is chosen if omitted. |
Usage
Evaluate the command’s output to set SSH_AUTH_SOCK in your shell, then use SSH normally:
The SSH token is gated by the use permission and can be bound to a workspace. ed25519 keys are supported today; RSA is planned. See SSH brokering.
Exit behavior
- A resolve failure in
veil runaborts before your command runs and returns a non-zero exit code. - Otherwise
veil runreturns the child process’s own exit code, so it’s safe to use directly in CI pipelines.
Next steps
- Tokens — mint the CI and SSH tokens these commands use.
- CI injection — patterns for using
veil runin pipelines. - SSH brokering — the full SSH setup.