Getting Started

Get from zero to injected secrets in under 5 minutes.

Prerequisites

• A varsafe account — sign up free

Installation

macOS / Linux / WSL

curl -fsSL https://varsafe.dev/install.sh | sh

Verify

varsafe --version

Quick Start

1. Login

Authenticate with your varsafe account:

varsafe login

This opens your browser for authentication. After confirming, your CLI is authenticated.

2. List Your Secrets

View secrets available in your current context:

varsafe list

To reveal actual values (this action is audited):

varsafe list --reveal

3. Set a Secret

Add or update a secret from the command line:

varsafe set DATABASE_URL "postgres://localhost/mydb"

4. Inject and Run

Run your application with secrets injected:

varsafe run -- npm run dev

That's it. Your application receives secrets as environment variables, but they never touch your filesystem.

5. Export When Needed

If you need a .env file for certain tools:

varsafe export -o .env

WARNING

Add .env to your .gitignore to prevent accidental commits.

Context management

Set your context with varsafe use -p my-api -e development — it's saved locally so subsequent commands use it automatically.

Project Setup

Once you're set up, the dashboard gives you a full overview of your secrets across all projects and environments:

Creating a team

1. Go to the dashboard
2. Click "Create team"
3. Name your team (e.g., "Acme Engineering")

Creating a project

1. Navigate to Teams in the dashboard
2. Click "Add project"
3. Name it to match your repository (e.g., "api-backend")

Every project comes with three default environments:

Environment	Purpose	Protected by Default
Development	Local development	No
Staging	Pre-production testing	No
Production	Live systems	Yes

You can create custom environments as needed.

Adding secrets

Via Dashboard:

1. Go to Secrets
2. Select your project and environment
3. Click "Add secrets"
4. Enter key-value pairs or import from .env

Via Bulk Import:

1. Click "Add secrets" → "Bulk"
2. Paste your .env file contents or drag-drop the file
3. Review detected secrets and confirm

Key format

Secret keys must start with a letter and contain only uppercase letters, digits, and underscores (e.g., DATABASE_URL, API_KEY).

Team Collaboration

Inviting Members

1. Expand your team in the Teams page
2. Click "Invite member"
3. Enter their email and select a role

Roles

Role	Non-Protected Envs	Protected Envs	Team Mgmt
Owner	Read/Write	Read/Write	Full
Admin	Read/Write	Read/Write	Yes
Developer	Read/Write	Read-only	—
Operator	Read-only	Read-only	—
Viewer	Read-only	No Access	—
Billing	No Access	No Access	Billing

Protected environments

Production is protected by default. You can mark any environment as protected to restrict write access. When an environment is protected:

• Owner / Admin — read/write access
• Developer / Operator — read-only access
• Viewer / Billing — no access

See Core Concepts for the full permissions matrix.

CI/CD Integration

For automated pipelines, create an API token instead of using your personal session:

1. Go to your team settings in the dashboard
2. Navigate to "API Tokens"
3. Create a new token with appropriate scope
4. Add the token to your CI/CD secrets as VARSAFE_API_TOKEN

# GitHub Actions example
- name: Deploy with secrets
  run: varsafe run -p my-api -e production -- ./deploy.sh
  env:
    VARSAFE_API_TOKEN: ${{ secrets.VARSAFE_API_TOKEN }}

Next Steps

• Core Concepts — Understand teams, projects, environments, and injection
• CLI Reference — Full command reference with examples
• Dashboard Guide — Managing secrets, teams, and audit logs
• API Tokens — Service accounts for CI/CD pipelines
• Security Model — How your secrets stay safe