Getting started

Up and running in minutes

Three steps to access your secrets from anywhere.

1

Install the gem

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

$ gem install vaultez-cli

2

Log in

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.

3

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... # Or pass it directly with --token $ vaultez fetch --token="vz_..." DATABASE_URL=postgres://user:pass@host:5432/mydb REDIS_URL=redis://localhost:6379 SECRET_KEY_BASE=abc123...

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: --token Use a project token instead of the saved session --version Show the installed CLI version Examples: vaultez login vaultez fetch --project="Backend" vaultez fetch --project="Backend" --secret="DATABASE_URL" vaultez fetch --token="vz_..." vaultez fetch --token="vz_..." --secret="DATABASE_URL"

Log in

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 in KEY=value format — ready to pipe, source, or redirect to a .env file.

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

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 >> $GITHUB_ENV

hcl

data "external" "vaultez" {
  program = ["vaultez", "fetch", "--format=json"]
}

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

$ VAULTEZ_TOKEN=vz_... terraform apply

ruby — config/initializers/vaultez.rb

if ENV["VAULTEZ_TOKEN"].present?
  output, status = Open3.capture2("vaultez", "fetch")
  if status.success?
    output.each_line do |line|
      key, value = line.chomp.split("=", 2)
      ENV[key] ||= value if key && value
    end
  end
end

dockerfile

RUN gem install vaultez-cli

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

package.json

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

$ VAULTEZ_TOKEN=vz_... npm run dev # runs vaultez fetch > .env.local, then starts Next.js

Ready to try it?

Create a free Vaultez account, then install the CLI.

Create free account View pricing

Your secrets, wherever you work