Quick Start¶

Get started with SecretZero in 5 minutes! This guide will walk you through creating your first secret.

Prerequisites¶

Make sure you have SecretZero installed:

pip install secretzero

See the Installation Guide for more options.

Step 1: Initialize a Project¶

Create a new Secretfile in your project directory:

secretzero create

This creates a Secretfile.yml with example configuration:

version: "1.0"
metadata:
  name: my-project
  description: My first SecretZero project

secrets:
  api_key:
    template:
      type: api_key
      fields:
        - name: value
          generator:
            type: random-string
            length: 32
    targets:
      - type: local-file
        path: .env
        format: dotenv

Step 2: Validate Configuration¶

Validate your Secretfile:

secretzero validate

Expected output:

✓ Configuration is valid
✓ Found 1 secret(s)
✓ Found 1 target(s)

Step 3: Preview Secret Generation¶

See what would be generated without making changes:

secretzero sync --dry-run

Expected output:

[Dry Run] Would generate secret: api_key
  ✓ Would generate field: value (random-string, length=32)
  ✓ Would write to: .env (dotenv format)

[Dry Run] Summary:
  Secrets to generate: 1
  Secrets to skip: 0
  Targets to update: 1

Step 4: Generate the Secret¶

Generate and sync the secret:

secretzero sync

Expected output:

✓ Generated secret: api_key
  ✓ Generated field: value
  ✓ Wrote to: .env

✓ Updated lockfile: .gitsecrets.lock

Summary:
  Generated: 1
  Skipped: 0
  Failed: 0

Step 5: Verify the Results¶

Check the generated secret in your .env file:

cat .env

Output:

API_KEY=abcd1234efgh5678ijkl9012mnop3456

Check the lockfile:

cat .gitsecrets.lock

The lockfile contains hashed values and metadata:

{
  "version": "1.0",
  "secrets": {
    "api_key": {
      "fields": {
        "value": {
          "hash": "sha256:a1b2c3d4...",
          "generated_at": "2026-02-16T12:00:00Z",
          "algorithm": "random-string"
        }
      },
      "targets": [".env"],
      "last_modified": "2026-02-16T12:00:00Z"
    }
  }
}

Step 6: View Secret Status¶

Check the status of your secret:

secretzero show api_key

Output:

Secret: api_key
Type: api_key
Status: ✓ Generated

Fields:
  value:
    Algorithm: random-string
    Generated: 2026-02-16 12:00:00 UTC
    Hash: sha256:a1b2c3d4...

Targets:
  ✓ .env (dotenv format)

Last Modified: 2026-02-16 12:00:00 UTC

🎉 Congratulations!¶

You've successfully:

✅ Created a Secretfile
✅ Validated the configuration
✅ Generated a secret
✅ Synced it to a local file
✅ Tracked it in a lockfile

What's Next?¶

Now that you understand the basics, explore more features:

Add More Secrets¶

Edit your Secretfile.yml to add more secrets:

secrets:
  api_key:
    # ... existing configuration ...

  database_password:
    template:
      type: password
      fields:
        - name: value
          generator:
            type: random-password
            length: 32
            include_symbols: true
    targets:
      - type: local-file
        path: .env
        format: dotenv

Then sync again:

secretzero sync

Use Different Targets¶

Store secrets in multiple locations:

secrets:
  api_key:
    template:
      type: api_key
      fields:
        - name: value
          generator:
            type: random-string
            length: 32
    targets:
      - type: local-file
        path: .env
        format: dotenv
      - type: local-file
        path: config.json
        format: json
      - type: local-file
        path: config.yml
        format: yaml

Add Cloud Providers¶

Store secrets in AWS Secrets Manager:

providers:
  aws:
    type: aws
    auth:
      type: ambient  # Uses IAM roles/profiles

secrets:
  api_key:
    template:
      type: api_key
      fields:
        - name: value
          generator:
            type: random-string
            length: 32
    targets:
      - type: aws-secretsmanager
        provider: aws
        name: /prod/api_key
      - type: local-file
        path: .env
        format: dotenv

First install AWS support:

pip install secretzero[aws]

Then sync:

secretzero sync

Test Provider Connectivity¶

Before syncing to cloud providers, test connectivity:

secretzero test

This verifies that:

Provider authentication is working
Required permissions are available
Network connectivity is OK

Add Rotation Policies¶

Automatically rotate secrets based on time:

secrets:
  api_key:
    template:
      type: api_key
      fields:
        - name: value
          generator:
            type: random-string
            length: 32
    rotation:
      period: 90d  # Rotate every 90 days
    targets:
      - type: local-file
        path: .env
        format: dotenv

Check rotation status:

secretzero rotate --dry-run

Execute rotation:

secretzero rotate

Common Use Cases¶

Here are some quick examples for common scenarios:

Database Credentials¶

secrets:
  db_password:
    template:
      type: database
      fields:
        - name: username
          generator:
            type: static
            value: myapp_user
        - name: password
          generator:
            type: random-password
            length: 32
        - name: host
          generator:
            type: static
            value: db.example.com
        - name: port
          generator:
            type: static
            value: "5432"
    targets:
      - type: local-file
        path: .env
        format: dotenv

API Tokens¶

secrets:
  github_token:
    template:
      type: token
      fields:
        - name: value
          generator:
            type: random-string
            length: 40
            charset: hex
    targets:
      - type: local-file
        path: .env
        format: dotenv
        key: GITHUB_TOKEN

Multi-Field Secrets¶

secrets:
  oauth_credentials:
    template:
      type: oauth
      fields:
        - name: client_id
          generator:
            type: random-string
            length: 32
        - name: client_secret
          generator:
            type: random-password
            length: 64
    targets:
      - type: local-file
        path: oauth.json
        format: json

Tips and Best Practices¶

Use Dry Run First

Always use --dry-run to preview changes before applying them:

secretzero sync --dry-run

Protect Your Secrets

Add secret files to .gitignore:

.env
.env.local
.gitsecrets.lock

Environment Variables

You can override generated values with environment variables:

export API_KEY_VALUE="my-existing-key"
secretzero sync  # Will use the environment variable

Lockfile Benefits

The lockfile (.gitsecrets.lock):

Tracks secret history
Prevents unnecessary regeneration
Enables drift detection
Supports compliance audits

Next Steps¶

Ready to learn more?

First Project → - Build a complete multi-secret project
Basic Concepts → - Understand the architecture
User Guide → - Detailed documentation
Examples → - Real-world examples

Getting Help¶

Need assistance?

FAQ - Common questions
Troubleshooting - Solutions to common issues
GitHub Issues - Report bugs
Discussions - Ask questions