Skip to main content

Need the shared validation model?

Use Fundamentals for the shared schema model. Use this guide for CLI rule syntax and commands.
Validation happens entirely on your device. Ghostable never sees your plaintext data or schema details, maintaining a true zero-knowledge design.

​
Configuration

All validation lives in the .ghostable directory:
Example
.ghostable/ ghostable.yaml schema.yaml schemas/ production.yaml staging.yaml local.yaml
The global .ghostable/schema.yaml file defines rules applied to every environment in the project. Any file under .ghostable/schemas/ will override rules for that specific environment. For example, rules placed inside .ghostable/schemas/production.yaml will only be applied to the production environment.
Use global rules for consistency across environments. Add overrides only when environments need stricter rules.

​
Schema Format

Each key represents an environment variable, followed by an array of rules.
schema.yaml
APP_NAME:
    - required
    - string
    - max:255

APP_ENV:
    - required
    - in:local,staging,production

APP_DEBUG:
    - required
    - boolean

DATABASE_URL:
    - required
    - regex:^postgres://
Keep schemas in version control — they serve as your environment contract.

​
Supported Rules

Presence & Type
RuleDescription
requiredThe variable must be defined. Validation fails if missing.
nullableThe variable can be empty or null without triggering an error.
booleanAccepts values that can be interpreted as boolean (true, false, 1, 0).
integerMust be a whole number with no decimals.
numericMust be a number (integer or floating-point).
stringMust be a string value.
in:<values>Restricts value to a specific list, e.g. in:local,staging,production.
Format / Pattern
RuleDescription
urlMust be a valid URL (e.g., https://example.com).
emailMust be a valid email address.
regex:<pattern>Must match a regular expression. Example: regex:^v[0-9]+\\.[0-9]+$.
starts_with:<text>Value must begin with the given prefix (e.g., starts_with:sk_).
ends_with:<text>Value must end with the given suffix (e.g., ends_with:=).
Length / Range
RuleDescription
min:<n>Minimum allowed length (for strings) or value (for numbers).
max:<n>Maximum allowed length (for strings) or value (for numbers).

​
Usage

Validate your local environment before pushing or deploying: 
ghostable env validate --env production
This command:
  • Loads .ghostable/schema.yaml
  • Merges any overrides from .ghostable/schemas/production.yaml
  • Validates your .env values against all defined rules
You’ll see friendly, human-readable errors, for example: 
❌ APP_KEY must start with "base64:"
❌ APP_DEBUG must be "false"

​
Running validation in CI

Because validation runs locally with your device keys, it fits naturally into CI pipelines. For example, a GitHub Actions job can block merges when a .env drifts from the schema:
github-actions
name: Validate env

on:
    pull_request:
    workflow_dispatch:

jobs:
    validate-env:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4
            - uses: actions/setup-node@v4
              with:
                  node-version: 20
            - run: npm install @ghostable/cli@latest
            - name: Validate production schema
              env:
                  GHOSTABLE_TOKEN: ${{ secrets.GHOSTABLE_TOKEN }}
              run: |
                  ghostable login --token "$GHOSTABLE_TOKEN"
                  ghostable env validate --env production
When rules fail, the CLI exits non-zero with the same human-readable output shown earlier, so the workflow clearly highlights which variables need to change before deployment.