Varlock Skill for Claude Code

https://github.com/wrsmith108/varlock-claude-skill
Admin
A Claude skill for secure-by-default environment variable management, ensuring secrets are never...
Tokens:5,925
Snippets:66
Trust Score:7.5
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Docker Integration - Install and Run Varlock

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

This Dockerfile snippet demonstrates how to install the Varlock CLI within a container and configure it to run as the container's entrypoint. It ensures Varlock is available and used for starting the application.

```dockerfile
# Install Varlock in container
RUN curl -sSfL https://varlock.dev/install.sh | sh -s -- --force-no-brew \
    && ln -s /root/.varlock/bin/varlock /usr/local/bin/varlock

# Validate at container start
CMD ["varlock", "run", "--", "npm", "start"]
```

--------------------------------

### Installing Varlock CLI

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Provides the bash commands to install the Varlock CLI tool. It includes fetching the install script, executing it, and adding the Varlock binary directory to the system's PATH.

```bash
# Install Varlock CLI
curl -sSfL https://varlock.dev/install.sh | sh -s -- --force-no-brew

# Add to PATH (add to ~/.zshrc or ~/.bashrc)
export PATH="$HOME/.varlock/bin:$PATH"

# Verify
varlock --version
```

--------------------------------

### Varlock Schema File Example

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Illustrates the structure and syntax of a Varlock `.env.schema` file. It demonstrates how to define global defaults, application variables, database credentials, and API keys with various security and type annotations.

```bash
# Global defaults
# @defaultSensitive=true @defaultRequired=infer

# Application
# @type=enum(development,staging,production) @sensitive=false
NODE_ENV=development

# @type=port @sensitive=false
PORT=3000

# Database - SENSITIVE
# @type=url @required
DATABASE_URL=

# @type=string @required @sensitive
DATABASE_PASSWORD=

# API Keys - SENSITIVE
# @type=string(startsWith=sk_) @required @sensitive
STRIPE_SECRET_KEY=

# @type=string(startsWith=pk_) @sensitive=false
STRIPE_PUBLISHABLE_KEY=
```

--------------------------------

### Install Varlock CLI

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/README.md

Installs the Varlock Command Line Interface (CLI) using a script. This is a prerequisite for using Varlock's features within your environment. It ensures the Varlock binary is available in your PATH.

```bash
curl -sSfL https://varlock.dev/install.sh | sh -s -- --force-no-brew
export PATH="$HOME/.varlock/bin:$PATH"
```

--------------------------------

### Troubleshooting 'varlock: command not found' (Bash)

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Provides steps to troubleshoot the 'varlock: command not found' error. It includes checking the installation path and adding Varlock to the system's PATH environment variable.

```bash
# Check installation
ls ~/.varlock/bin/varlock

# Add to PATH
export PATH="$HOME/.varlock/bin:$PATH"

# Or use full path
~/.varlock/bin/varlock load
```

--------------------------------

### Install Varlock Claude Plugin

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/README.md

Installs the Varlock Claude Skill as a plugin for Claude. This is the recommended installation method for ease of use and integration.

```bash
claude plugin add github:wrsmith108/varlock-claude-skill
```

--------------------------------

### Varlock Schema File Example

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/README.md

Defines environment variables with types, sensitivity, and requirements using Varlock schema annotations. This file ensures consistent and secure handling of secrets.

```bash
# Global defaults
# @defaultSensitive=true @defaultRequired=infer

# Public config
# @type=enum(development,staging,production) @sensitive=false
NODE_ENV=development

# Sensitive secrets
# @type=string(startsWith=sk_) @required @sensitive
STRIPE_SECRET_KEY=

# @type=url @required @sensitive
DATABASE_URL=
```

--------------------------------

### Manually Install Varlock Claude Skill

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/README.md

Manually installs the Varlock Claude Skill by cloning the repository into the local Claude skills directory. This method provides more control over the installation location.

```bash
git clone https://github.com/wrsmith108/varlock-claude-skill ~/.claude/skills/varlock
```

--------------------------------

### Using Varlock for Secret Validation

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Provides an example of how Varlock ensures secrets are validated and masked in output, preventing accidental exposure in error messages or logs. It contrasts an unsafe direct variable check with the secure `varlock load` command.

```bash
# ❌ NEVER DO THIS - exposes secret in error
test -n "$API_KEY" && echo "Key: $API_KEY"

# ✅ DO THIS - Varlock validates and masks
varlock load
# Output shows: API_KEY 🔐sensitive └ ▒▒▒▒▒
```

--------------------------------

### Varlock Type Annotations

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Details the various type annotations available in Varlock's `.env.schema` file for validating environment variable values. Includes examples for string, URL, port, boolean, and enum types, along with string prefix and substring validation.

```bash
# @type=string
# @type=string(startsWith=X)
# @type=string(contains=X)
# @type=url
# @type=port
# @type=boolean
# @type=enum(a,b,c)
```

--------------------------------

### Varlock Clerk Skill Schema Example

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/README.md

Illustrates how to define sensitive and non-sensitive variables for the Clerk authentication system using Varlock schema annotations. This helps in differentiating between public and private information.

```bash
# Test passwords are sensitive
# @type=string @sensitive
TEST_ADMIN_PASSWORD=

# Test emails are NOT sensitive (contain +clerk_test)
# @type=string(contains=+clerk_test) @sensitive=false
TEST_ADMIN_EMAIL=
```

--------------------------------

### Initializing Varlock Project Schema

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Shows how to initialize a Varlock project by creating the `.env.schema` file. It covers generating the schema from an existing `.env` file or creating an empty one manually.

```bash
# Create .env.schema from existing .env
varlock init

# Or create manually
touch .env.schema
```

--------------------------------

### Validating Environment with Varlock Load

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Demonstrates different ways to use the `varlock load` command for environment validation. It covers checking all variables, using quiet mode for success, and specifying a particular environment.

```bash
# Check all variables (safe - masks sensitive values)
varlock load

# Quiet mode (no output on success)
varlock load --quiet

# Check specific environment
varlock load --env=production
```

--------------------------------

### 1Password Integration in .env.schema

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Shows how to integrate 1Password secrets into the `.env.schema` file using the `exec` function. This allows Varlock to fetch secrets dynamically from 1Password when loading environment variables.

```bash
# In .env.schema
# @type=string @sensitive
API_KEY=exec('op read "op://vault/item/field"')
```

--------------------------------

### Reading .env Files Safely with Varlock

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Illustrates the correct method for interacting with `.env` files when using Varlock. It shows that directly reading the file is unsafe, while checking the schema or using `varlock load` for masked values is secure.

```bash
# ❌ NEVER DO THIS - exposes all secrets
cat .env
less .env
Read tool on .env file

# ✅ DO THIS - read schema (safe) not values
cat .env.schema
varlock load  # Shows masked values
```

--------------------------------

### Troubleshooting 'Schema validation failed' (Bash)

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Offers guidance on resolving 'Schema validation failed' errors. It suggests using `varlock load` to see detailed errors and lists common fixes such as adding missing variables or correcting type mismatches.

```bash
# Check which variables are missing/invalid
varlock load  # Shows detailed errors

# Common fixes:
# - Add missing required variables to .env
# - Fix type mismatches (port must be number)
# - Check string prefixes match schema
```

--------------------------------

### Running Commands with Secrets via Varlock Run

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Explains how to execute commands securely using `varlock run`. This command injects validated environment variables into the command's execution context, ensuring secrets are available to the command but not exposed in output.

```bash
# Inject validated env into command
varlock run -- npm start
varlock run -- node script.js
varlock run -- pytest

# Secrets are available to the command but never printed
```

--------------------------------

### Environment-Specific Values in .env.schema

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Demonstrates how to define environment-specific values in `.env.schema` using the `env` function. This allows for default values or values that change based on the `NODE_ENV` variable.

```bash
# In .env.schema
# @type=url
API_URL=env('API_URL_${NODE_ENV}', 'http://localhost:3000')
```

--------------------------------

### Varlock Quick Reference Commands

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/README.md

Provides essential Varlock commands for managing environment variables securely. These commands help in loading, validating, and running applications with injected secrets.

```bash
# Validate all secrets (shows masked values)
varlock load

# Quiet validation (no output on success)
varlock load --quiet

# Run command with secrets injected
varlock run -- npm start

# View schema (safe - no values)
cat .env.schema
```

--------------------------------

### Including Secrets in Commands Safely with Varlock

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Explains how to securely include secrets in command-line operations. It discourages hardcoding secrets directly into commands and promotes using environment variables or `varlock run` for secure execution.

```bash
# ❌ NEVER DO THIS - secret in command history
curl -H "Authorization: Bearer sk_live_xxx" https://api.example.com

# ✅ DO THIS - use environment variable
curl -H "Authorization: Bearer $API_KEY" https://api.example.com
# Or better: varlock run -- curl ...
```

--------------------------------

### Debug Authentication (Bash)

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Provides safe bash commands to debug authentication by checking for the presence and format of keys using Varlock. It includes checking for specific prefixes without revealing sensitive values.

```bash
# ✅ Safe approach - check presence and format
varlock load  # Validates types and required fields

# Check if key has correct prefix (without showing value)
varlock load 2>&1 | grep -E "(CLERK|AUTH)"

# ❌ Never do
printenv | grep KEY
```

--------------------------------

### Validating Secrets with Varlock CLI

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Demonstrates how to validate environment variables using the Varlock CLI without exposing sensitive data. It contrasts unsafe echo commands with the secure `varlock load --quiet` command.

```bash
# ❌ NEVER DO THIS - exposes secret to Claude's context
echo $CLERK_SECRET_KEY
cat .env | grep SECRET
printenv | grep API

# ✅ DO THIS - validates without exposing
varlock load --quiet && echo "✓ Secrets validated"
```

--------------------------------

### npm Scripts for Environment Management

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Provides essential npm scripts for integrating Varlock into a project's `package.json`. These scripts facilitate environment validation, checking, and running applications securely.

```json
{
  "scripts": {
    "env:validate": "varlock load",
    "env:check": "varlock load --quiet || echo 'Environment validation failed'",
    "prestart": "varlock load --quiet",
    "start": "varlock run -- node server.js"
  }
}
```

--------------------------------

### Pattern: Safe Secret Rotation Workflow

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Outlines a secure workflow for rotating secrets. It emphasizes updating secrets in external sources first, manually updating the `.env` file (not via Claude), validating the new value with Varlock, and then syncing with systems like GitHub Secrets.

```bash
# 1. Update secret in external source (1Password, AWS, etc.)
# 2. Update .env file manually (don't use Claude for this)
# 3. Validate new value works
varlock load

# 4. If using GitHub Secrets, sync (values not shown)
./scripts/update-github-secrets.sh
```

--------------------------------

### Pattern: Validate Environment Before Operations

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Presents a common pattern for ensuring the environment is correctly configured before proceeding with critical operations. It uses `varlock load --quiet` and checks the exit code to halt execution if validation fails.

```bash
# Always validate environment first
varlock load --quiet || {
  echo "❌ Environment validation failed"
  exit 1
}

# Then proceed with operation
npm run build
```

--------------------------------

### Troubleshooting 'Sensitive value exposed in logs' (Bash)

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Outlines steps to address sensitive values being exposed in logs. It emphasizes rotating secrets, checking for the `@sensitive` annotation in `.env.schema`, and ensuring Varlock commands are used instead of direct `echo` or `cat`.

```bash
# 1. Rotate the exposed secret immediately
# 2. Check .env.schema has @sensitive annotation
# 3. Ensure using varlock commands, not echo/cat

# Add missing sensitivity:
# Before: API_KEY=
# After:  # @type=string @sensitive
#         API_KEY=
```

--------------------------------

### Checking Varlock Schema Safely

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Shows how to safely inspect the Varlock schema definition. It highlights that the schema file itself contains no sensitive values and can be read directly or filtered to list expected variables.

```bash
# Schema is safe to read - contains no values
cat .env.schema

# List expected variables
grep "^[A-Z]" .env.schema
```

--------------------------------

### Check if API Key is Set (Bash)

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Demonstrates a safe method to check if the API_KEY secret is loaded by Varlock, displaying its masked value. It contrasts this with an unsafe method of directly echoing the environment variable.

```bash
# ✅ Safe approach
varlock load 2>&1 | grep "API_KEY"
# Shows: ✅ API_KEY 🔐sensitive └ ▒▒▒▒▒

# ❌ Never do
echo $API_KEY
```

--------------------------------

### GitHub Actions - Load Secrets

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

This snippet shows how to load secrets from GitHub Secrets within a GitHub Actions workflow using Varlock. It sets environment variables for DATABASE_URL and API_KEY before running a quiet Varlock load command.

```yaml
name: Validate environment
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
    API_KEY: ${{ secrets.API_KEY }}
  run: varlock load --quiet
```

--------------------------------

### AWS Secrets Manager Integration in .env.schema

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/skills/varlock/SKILL.md

Illustrates integrating AWS Secrets Manager secrets into the `.env.schema` file using the `exec` function. Varlock will retrieve the secret value from AWS when needed.

```bash
# In .env.schema
# @type=string @sensitive
DB_PASSWORD=exec('aws secretsmanager get-secret-value --secret-id prod/db')
```

--------------------------------

### Varlock Dockerfile Integration

Source: https://github.com/wrsmith108/varlock-claude-skill/blob/main/README.md

Integrates Varlock into a Dockerfile to securely manage environment variables for containerized applications. It sets Varlock as the entrypoint to ensure secrets are handled correctly.

```dockerfile
# Use Varlock as entrypoint
CMD ["varlock", "run", "--", "npm", "start"]
```
Tokens:
Raw