Validation

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

Rule	Description
`required`	The variable must be defined. Validation fails if missing.
`nullable`	The variable can be empty or null without triggering an error.
`boolean`	Accepts values that can be interpreted as boolean (`true`, `false`, `1`, `0`).
`integer`	Must be a whole number with no decimals.
`numeric`	Must be a number (integer or floating-point).
`string`	Must be a string value.
`in:<values>`	Restricts value to a specific list, e.g. `in:local,staging,production`.

Format / Pattern

Rule	Description
`url`	Must be a valid URL (e.g., `https://example.com`).
`email`	Must 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

Rule	Description
`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.

Workflows

Automation & CI

Reference

Need the shared validation model?

Configuration

Schema Format

Supported Rules

Usage

Running validation in CI

Need the shared validation model?

​Configuration

​Schema Format

​Supported Rules

​Usage

​Running validation in CI

Configuration

Schema Format

Supported Rules

Usage

Running validation in CI