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:

Pin a specific version by setting VEIL_VERSION:

Manual download

Prefer to download the binary yourself? Grab the right asset for your platform, chmod +x it, and move it onto your PATH. Replace latest with a version tag (e.g. v0.1.1) to pin.

On Windows, download veil-windows-x64.exe, rename it to veil.exe, and put it on your PATH. 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.

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

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. Masking is line-buffered, so a value split across writes is still caught.

Preview with --print

Use --print to verify a manifest in CI setup without running anything. It lists the variables that would be set. To keep the value’s length and shape secret, --print shows only whether each variable is set — never any characters of the value.

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.

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 run aborts before your command runs and returns a non-zero exit code.
• Otherwise veil run returns 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 run in pipelines.
• SSH brokering — the full SSH setup.