Terminal access

Your secrets, wherever you work

Pull any secret from your terminal in one command. Secure by default — 2FA enforced for interactive logins, project tokens for pipelines. Included in Pro.

$ gem install vaultez-cli

Getting started

Up and running in minutes

Three steps to access your secrets from anywhere.

Install the gem

Requires Ruby 3.0 or higher. Works on macOS, Linux, and Windows.

$ gem install vaultez-cli

Authenticate with your Vaultez email, password, and 2FA code. All accounts require two-factor authentication. Your session token is stored locally in ~/.vaultez/config.yml.

$ vaultez login Email: you@company.com Password: ········ One-time code (Proton Authenticator / TOTP): 487 219 Logged in successfully.

Fetch a secret

Fetch a single secret or pull an entire project's secrets at once.

$ vaultez fetch --project="Backend" --secret="DATABASE_URL" postgres://user:pass@host:5432/mydb

Authentication

Two ways to authenticate

Interactive logins for humans. Project tokens for pipelines.

Interactive login

For developers working locally. Run vaultez login and enter your email, password, and 2FA code. Your session token is saved to ~/.vaultez/config.yml and reused on every command. Gives access to all companies, projects, and secrets your account can see.

$ vaultez login Email: you@company.com Password: ········ One-time code: 487 219 Logged in successfully.

Project tokens

For CI/CD pipelines and automation. Create a project token in your project's Tokens tab. Set it as VAULTEZ_TOKEN in your pipeline environment. No password or 2FA needed — the token already knows which project it belongs to, so no --project flag is required.

# Using an environment variable $ VAULTEZ_TOKEN=vz_... vaultez fetch DATABASE_URL='postgres://user:pass@host:5432/mydb' REDIS_URL='redis://localhost:6379' SECRET_KEY_BASE='abc123...' # Always use the environment variable, never a --token flag — # CLI arguments are visible to other local users via `ps` # and get saved in shell history.

Commands

Full command reference

Everything the CLI can do.

$ vaultez --help Vaultez CLI — secure secret management from your terminal Usage: vaultez <command> [options] Commands: login Authenticate with email, password, and 2FA code logout Revoke the current session token fetch Fetch secrets from a project config Set default company or token help Show help for any command Options: --version Show the installed CLI version Examples: vaultez login vaultez fetch --project="Backend" vaultez fetch --project="Backend" --secret="DATABASE_URL" VAULTEZ_TOKEN="vz_..." vaultez fetch VAULTEZ_TOKEN="vz_..." vaultez fetch --secret="DATABASE_URL"

Prompts for email, password, and your 2FA code. Stores a session token in ~/.vaultez/config.yml. You can also pass a backup code in place of the 2FA code if you don't have your authenticator app.

$ vaultez login Email: you@company.com Password: ········ One-time code: 487 219 Logged in successfully.

Log out

Revokes the current session token on the server and removes it from ~/.vaultez/config.yml. Use this when leaving a shared machine.

$ vaultez logout Logged out. Session token revoked.

List companies

List all companies your account belongs to. Shows your role in each.

$ vaultez fetch --companies Companies: Acme Corp (owner) Side Project (member)

List projects

List all projects in a company you have access to.

$ vaultez fetch --company="Acme Corp" --projects Projects in Acme Corp: Backend (owner) Frontend (member)

Fetch all secrets in a project

Returns all secrets as KEY='value' lines. Every value is quoted, so the output is safe to eval or source whatever the secret contains. Errors and notices go to stderr, never into your output.

$ vaultez fetch --project="Backend" DATABASE_URL='postgres://user:pass@host:5432/mydb' REDIS_URL='redis://localhost:6379' SECRET_KEY_BASE='abc123...'

Load secrets into your shell or a .env file

Pick an output with --format: env (default), shell (export KEY='value'), dotenv for .env files, github for $GITHUB_ENV, or json. Secrets whose names aren't valid variable names (letters, numbers and _) are skipped with a warning.

# Into the current shell $ eval "$(vaultez fetch --project="Backend")" # Into a .env file, stopping if the fetch fails $ vaultez fetch --project="Backend" --format=dotenv > .env.local || exit 1

Fetch a single secret

Returns the plain value only — pipes cleanly into scripts and shell variables.

$ export DATABASE_URL=$(vaultez fetch --project="Backend" --secret="DATABASE_URL")

Set a default company

Skip the --company flag on every command by setting a default once.

$ vaultez config --default-company="Acme Corp" Default company set to "Acme Corp".

Integrations

Connect your pipelines

Create a project token in your project's Tokens tab, then add it to your pipeline as VAULTEZ_TOKEN. Each example below fetches all secrets from a project and exposes them as environment variables.

yaml

- name: Fetch secrets from Vaultez
  env:
    VAULTEZ_TOKEN: ${{ secrets.VAULTEZ_TOKEN }}
  run: |
    gem install vaultez-cli
    vaultez fetch --format=github >> "$GITHUB_ENV"

hcl

data "external" "vaultez" {
  program = ["sh", "-c", "vaultez fetch --format=json | jq 'map({(.name): .value}) | add // {}'"]
}

resource "aws_db_instance" "main" {
  password = data.external.vaultez.result["DB_PASSWORD"]
}

$ VAULTEZ_TOKEN=vz_... terraform apply

ruby — config/initializers/vaultez.rb

require "open3"

if ENV["VAULTEZ_TOKEN"].present?
  output, status = Open3.capture2("vaultez", "fetch", "--format=json")
  if status.success?
    JSON.parse(output).each do |secret|
      ENV[secret["name"]] ||= secret["value"]
    end
  end
end

dockerfile

RUN gem install vaultez-cli

$ docker run -e VAULTEZ_TOKEN=vz_... myapp \ sh -c 'vaultez fetch --format=dotenv > .env && ./start.sh'

package.json

{
  "scripts": {
    "predev":   "vaultez fetch --format=dotenv > .env.local",
    "dev":      "next dev",
    "prebuild": "vaultez fetch --format=dotenv > .env.local",
    "build":    "next build"
  }
}

$ VAULTEZ_TOKEN=vz_... npm run dev # writes .env.local, then starts Next.js (stops if the fetch fails)