> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ghostable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Validation

> Ghostable lets you define lightweight validation rules that enforce the correctness of your environment variables before they’re pushed or deployed.

<Card title="Need the shared validation model?" icon="circle-info" href="/fundamentals/v2/security-and-operations/validation-rules">
  Use Fundamentals for the shared schema model. Use this guide for CLI rule syntax and commands.
</Card>

<Note>
  Validation happens entirely on your device. Ghostable never sees your plaintext data or schema
  details, maintaining a true zero-knowledge design.
</Note>

***

## Configuration

All validation lives in the `.ghostable` directory:

```yaml Example theme={null}
.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.

<Tip>
  Use global rules for consistency across environments. Add overrides only when environments need
  stricter rules.
</Tip>

***

## Schema Format

Each key represents an environment variable, followed by an array of rules.

```yaml schema.yaml theme={null}
APP_NAME:
    - required
    - string
    - max:255

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

APP_DEBUG:
    - required
    - boolean

DATABASE_URL:
    - required
    - regex:^postgres://
```

<Tip>Keep schemas in version control — they serve as your environment contract.</Tip>

***

## 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:

```bash theme={null}
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:

```bash theme={null}
❌ 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:

```yaml github-actions theme={null}
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.