Infisical

Overview

Infisical is an all-in-one platform to securely manage application configuration and secrets across your team and infrastructure. Used by Fortune 500 enterprises, international governments, and fastest-growing startups, Infisical helps you save time and boost security.

ZeroStarter includes Infisical configuration via .infisical.json for seamless secrets management across development, staging, and production environments.

Why Infisical?

Secure Secret Management - Centralized, encrypted storage for all secrets
Environment Sync - Automatically sync secrets across dev, staging, and production
Team Collaboration - Share secrets securely with team members
Version Control - Track secret changes and roll back if needed
CLI Integration - Export secrets to .env files for local development
Self-Hosting Option - Full control over your infrastructure

Self-Hosting

Deploy Infisical to your own infrastructure with one click:

Why self-host?

Data Sovereignty - Keep secrets in your own infrastructure
Custom Compliance - Meet specific regulatory requirements
Cost Control - No per-seat pricing for large teams
Network Isolation - Secrets never leave your VPC

Project Configuration

ZeroStarter includes a .infisical.json file at the repository root:

.infisical.json

{
  "workspaceId": "0d62b0f6-cdd4-4c8e-9e27-f977aadc123d",
  "defaultEnvironment": "",
  "gitBranchToEnvironmentMapping": null
}

Configuration fields

workspaceId - Your Infisical project ID (generated during infisical init)
defaultEnvironment - Default environment to use (dev, staging, prod)
gitBranchToEnvironmentMapping - Map Git branches to Infisical environments

Installation

Install Infisical CLI

Install the Infisical CLI globally using Bun:

bun add -g @infisical/cli

Verify installation:

infisical --version

Setup

Authenticate with your Infisical account:Interactive login (recommended for local development):

infisical login

This opens a browser window for authentication.Non-interactive login (for CI/CD):

infisical login \
  --domain "<YOUR_DOMAIN>" \
  --email "<YOUR_EMAIL>" \
  --password "<YOUR_PASSWORD>" \
  --organization-id "<YOUR_ORGANIZATION_ID>" \
  --plain \
  --silent

Flag explanations

--plain - Outputs only the JWT access token without formatting (useful for scripting)
--silent - Disables all console messages except the access token
Use both flags together for CI/CD pipelines

Initialize project

Link your local ZeroStarter project to Infisical:

infisical init

This command:

Prompts you to select your Infisical project
Creates .infisical.json with your workspaceId
Establishes the connection for secret syncing

The .infisical.json file is already included in ZeroStarter. You can run infisical init to update the workspace ID.

Export secrets

Export secrets from Infisical to a local .env file:

infisical export --env=dev --output-file=.env.development

For different environments:

# Development environment
infisical export --env=dev --output-file=.env.development

# Staging environment
infisical export --env=staging --output-file=.env.staging

# Production environment
infisical export --env=prod --output-file=.env.production

CLI Reference

Authenticate with Infisical:

infisical login [OPTIONS]

Options:

--domain - Your Infisical instance URL
--email - Account email
--password - Account password
--organization-id - Organization ID
--plain - Output only JWT token
--silent - Suppress all messages except token

Init

Link local project to Infisical workspace:

infisical init

Creates .infisical.json with your project configuration.

Export

Export secrets to different file formats:

infisical export [OPTIONS]

Options:

--env=<environment> - Environment to export from (dev, staging, prod). Defaults to dev.
--output-file=<path> - Path to output file (e.g., .env.development)
--projectId=<id> - Override project ID from .infisical.json
--format=<format> - Output format (dotenv, json, yaml, csv)

Examples:

# Export to .env file
infisical export --env=dev --output-file=./.env.development

# Export as JSON
infisical export --env=prod --format=json --output-file=secrets.json

# Override project ID
infisical export --env=staging --projectId=abc123 --output-file=.env.staging

Environment Structure

ZeroStarter uses these environment files:

zerostarter/
├── .env.example          # Template with all required variables
├── .env.development      # Development secrets (git-ignored)
├── .env.staging          # Staging secrets (git-ignored)
└── .env.production       # Production secrets (git-ignored)

Environment Variables in ZeroStarter

Based on .env.example, ZeroStarter requires:

Tab Title
Tab Title
Tab Title

# Server Configuration
NODE_ENV=local
HONO_APP_URL=http://localhost:4000
HONO_TRUSTED_ORIGINS=http://localhost:3000

# Authentication
BETTER_AUTH_SECRET=<generate with: openssl rand -base64 32>

# OAuth Providers
GITHUB_CLIENT_ID=<from github.com/settings/developers>
GITHUB_CLIENT_SECRET=<from github.com/settings/developers>
GOOGLE_CLIENT_ID=<from console.cloud.google.com/apis/credentials>
GOOGLE_CLIENT_SECRET=<from console.cloud.google.com/apis/credentials>

# Database
POSTGRES_URL=<generate with: bunx pglaunch -k>

# Client Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:4000

# Analytics (Optional)
NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
NEXT_PUBLIC_POSTHOG_KEY=<from posthog.com>

# User Feedback (Optional)
NEXT_PUBLIC_USERJOT_URL=<your userjot URL>

Workflow

Local Development

Export secrets

infisical export --env=dev --output-file=.env.development

Start development servers

bun dev

The app automatically loads .env.development via @packages/env.

Update secrets

When secrets change in Infisical, re-run the export command:

infisical export --env=dev --output-file=.env.development

CI/CD Pipeline

Integrate Infisical in your CI/CD for automated secret injection:

.github/workflows/deploy.yml

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Infisical CLI
        run: |
          curl -1sLf 'https://dl.cloudsmith.io/public/infisical/infisical-cli/setup.deb.sh' | sudo -E bash
          sudo apt-get update && sudo apt-get install -y infisical
      
      - name: Export production secrets
        run: |
          infisical export \
            --env=prod \
            --output-file=.env.production \
            --token=${{ secrets.INFISICAL_TOKEN }}
      
      - name: Deploy
        run: |
          # Your deployment commands here
          bun run build

Store INFISICAL_TOKEN in GitHub Secrets for secure CI/CD authentication.

Git Branch Mapping

Map Git branches to Infisical environments automatically:

.infisical.json

{
  "workspaceId": "0d62b0f6-cdd4-4c8e-9e27-f977aadc123d",
  "defaultEnvironment": "dev",
  "gitBranchToEnvironmentMapping": {
    "main": "prod",
    "staging": "staging",
    "develop": "dev"
  }
}

With this configuration:

main branch → uses prod environment
staging branch → uses staging environment
develop branch → uses dev environment
Other branches → use defaultEnvironment (dev)

Security Best Practices

Never commit secrets

Ensure .env* files (except .env.example) are in .gitignore:

.gitignore

# Environment files
.env
.env.local
.env.development
.env.staging
.env.production
.env*.local

Use Infisical for all environments

Manage dev, staging, and prod secrets in Infisical, not local files.

Rotate secrets regularly

Use Infisical’s secret rotation features for sensitive credentials.

Use service tokens for CI/CD

Create dedicated service tokens with minimal permissions for automation.

Enable audit logs

Track who accessed or modified secrets in Infisical.

Troubleshooting

infisical: command not found

Install the CLI:

bun add -g @infisical/cli

Verify installation:

infisical --version

Authentication failed

Check your credentials are correct
Verify organization ID is accurate
Try interactive login: infisical login
Check Infisical instance is accessible

Project not found

Run infisical init to link project
Verify workspaceId in .infisical.json matches your Infisical project
Check you have access to the project in Infisical dashboard

Secrets not loading in app

Verify .env.development file exists and has correct variables
Check file is not in .gitignore preventing it from being read
Restart development servers: bun dev
Verify @packages/env is correctly configured

Developer Tools

Overview

Why Infisical?

Self-Hosting

Project Configuration

Installation

Install Infisical CLI

Setup

CLI Reference

Init

Export

Environment Structure

Environment Variables in ZeroStarter

Workflow

Local Development

CI/CD Pipeline

Git Branch Mapping

Security Best Practices

Troubleshooting

Read More

Build docs developers (and LLMs) love

Developer Tools

​Overview

​Why Infisical?

​Self-Hosting

​Project Configuration

​Installation

​Install Infisical CLI

​Setup

​CLI Reference

​Login

​Init

​Export

​Environment Structure

​Environment Variables in ZeroStarter

​Workflow

​Local Development

​CI/CD Pipeline

​Git Branch Mapping

​Security Best Practices

​Troubleshooting

​Read More

Build docs developers (and LLMs) love

Overview

Why Infisical?

Self-Hosting

Project Configuration

Installation

Install Infisical CLI

Setup

CLI Reference

Login

Init

Export

Environment Structure

Environment Variables in ZeroStarter

Workflow

Local Development

CI/CD Pipeline

Git Branch Mapping

Security Best Practices

Troubleshooting

Read More