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

# Config as code

> Manage InsForge auth, SMTP, storage, retention, and deployment settings declaratively from a single insforge.toml using the CLI's plan, apply, and export workflow.

## Overview

`insforge.toml` is a declarative, version-controlled snapshot of a subset of your project's config: auth policy, allowed redirect URLs, password rules, SMTP, storage upload size, realtime and schedule retention, and the deployment subdomain. The CLI provides three commands that work against this file:

* **`config plan`**: diff `insforge.toml` against the linked project. Shows what would change.
* **`config apply`**: push the diff to the live project. Per-change capability gating, env-resolved secrets, dry-run mode.
* **`config export`**: pull current project state and write a fresh `insforge.toml`. Useful for bootstrapping from an existing project.

You keep **one** `insforge.toml` in your repo. To apply it to a different environment (staging, prod, a teammate's local backend, or a self-hosted instance), point the CLI at a different project (re-link or use `--project-id`). Secrets are read from environment variables via `env(...)` references, so the file itself stays free of credentials and can be committed safely.

This works the same way on InsForge Cloud projects and on self-hosted OSS deployments.

<Note>
  All examples use `npx @insforge/cli`. Do not install the CLI globally.
</Note>

## Command summary

| Command                       | Purpose                                                              |
| ----------------------------- | -------------------------------------------------------------------- |
| `config plan`                 | Show diff between `insforge.toml` and live project state             |
| `config apply`                | Apply `insforge.toml` to the live project                            |
| `config apply --dry-run`      | Print the plan without applying                                      |
| `config apply --auto-approve` | Skip the interactive confirmation prompt (required in `--json` mode) |
| `config export`               | Pull live config and write `insforge.toml`                           |
| `config export --force`       | Overwrite an existing `insforge.toml` without confirmation           |

`config plan` and `config apply` read `insforge.toml`; pass `--file <path>` if it lives somewhere other than `./insforge.toml`. `config export` writes the file; pass `--out <path>` to write it to a custom location.

## Recommended workflow

<Steps>
  <Step title="Bootstrap from an existing project">
    If you already configured the project through the dashboard, export it once to get a working file:

    ```bash theme={null}
    npx @insforge/cli config export
    ```

    This writes `insforge.toml` reflecting the current backend state.
  </Step>

  <Step title="Commit it">
    Check `insforge.toml` into version control. Secrets are referenced via `env(...)`, so the file is safe to commit.
  </Step>

  <Step title="Edit and plan">
    Change the TOML, then preview the diff before applying:

    ```bash theme={null}
    npx @insforge/cli config plan
    ```
  </Step>

  <Step title="Apply">
    ```bash theme={null}
    npx @insforge/cli config apply
    ```

    Review the rendered plan and confirm. In CI, pass `--auto-approve` and `--json`.
  </Step>

  <Step title="Apply the same file elsewhere">
    To push the same config to staging or a self-hosted backend, point the CLI at the other project and re-run apply:

    ```bash theme={null}
    npx @insforge/cli --project-id <staging-project-id> config apply
    ```

    Secrets that differ between environments (SMTP password, etc.) are resolved per-environment from the local shell, so the TOML doesn't need to change.
  </Step>
</Steps>

## What `insforge.toml` covers

The file mirrors a curated subset of project config, the parts that are useful to manage declaratively. Anything not in this list still lives on the dashboard and the API.

| Section           | Keys                                                                                                                    |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `[auth]`          | `allowed_redirect_urls`, `require_email_verification`, `verify_email_method`, `reset_password_method`, `disable_signup` |
| `[auth.password]` | `min_length`, `require_number`, `require_lowercase`, `require_uppercase`, `require_special_char`                        |
| `[auth.smtp]`     | `enabled`, `host`, `port`, `username`, `password`, `sender_email`, `sender_name`, `min_interval_seconds`                |
| `[storage]`       | `max_file_size_mb`                                                                                                      |
| `[realtime]`      | `retention_days`                                                                                                        |
| `[schedules]`     | `retention_days`                                                                                                        |
| `[deployments]`   | `subdomain`                                                                                                             |

Because TOML has no `null` literal, use `retention_days = 0` to disable retention cleanup for realtime messages or schedule execution logs; `config apply` sends `null` to the backend for that value. Email templates, OAuth provider app credentials, buckets, realtime channels, functions, deployment environment variables, and secrets are not managed through this file.

A complete example:

```toml theme={null}
[auth]
require_email_verification = true
verify_email_method = "code"
reset_password_method = "code"
disable_signup = false
allowed_redirect_urls = [
  "https://app.example.com/auth/callback",
  "http://localhost:3000/auth/callback",
]

[auth.password]
min_length = 12
require_number = true
require_lowercase = true
require_uppercase = true
require_special_char = false

[auth.smtp]
enabled = true
host = "smtp.sendgrid.net"
port = 587
username = "apikey"
password = "env(SENDGRID_API_KEY)"
sender_email = "noreply@example.com"
sender_name = "Acme"

[storage]
max_file_size_mb = 100

[realtime]
retention_days = 7

[schedules]
retention_days = 0

[deployments]
subdomain = "acme-prod"
```

## `config plan`

```bash theme={null}
npx @insforge/cli config plan
npx @insforge/cli config plan --file ./config/insforge.toml
npx @insforge/cli --json config plan
```

`plan` reads `insforge.toml`, fetches live state via `/api/metadata` and the optional config endpoints for storage, realtime, and schedules, then prints a rendered diff. It also tags any section the live backend doesn't expose yet (older self-hosted versions, etc.). Apply will skip those instead of failing the whole run.

Use `plan` before every `apply` in interactive sessions, and as a CI gate to catch unintended drift.

## `config apply`

```bash theme={null}
npx @insforge/cli config apply
npx @insforge/cli config apply --dry-run
npx @insforge/cli config apply --auto-approve
npx @insforge/cli --json config apply --auto-approve
```

`apply` runs the same diff as `plan`, then walks the change set:

1. **Per-change capability gate.** Each change is checked against the backend's metadata or the section's config endpoint. If the backend doesn't support a section (e.g. an older self-hosted instance without SMTP exposed), that section is skipped with a named warning, and the rest of the changes still apply.
2. **Secret resolution.** `env(...)` references in the TOML are resolved at apply time from the local environment. If a referenced variable is missing, the command aborts before sending any update, so the backend isn't left half-configured.
3. **Per-section dispatch.** Each change is sent to the appropriate backend endpoint (`/api/auth/config`, `/api/auth/smtp-config`, `/api/storage/config`, `/api/realtime/config`, `/api/schedules/config`, `/api/deployments/slug`, etc.). Changes are independent, so a failure on one section won't roll back earlier successful sections.

Flags:

* `--dry-run` prints the plan and exits without applying.
* `--auto-approve` skips the interactive confirmation. Required when `--json` is set, since there's no TTY for the prompt.
* `--file <path>` overrides the default `./insforge.toml` location.

## `config export`

```bash theme={null}
npx @insforge/cli config export
npx @insforge/cli config export --out ./config/insforge.toml
npx @insforge/cli config export --force
```

`export` pulls the live project's configurable surface and writes it to a TOML file. Use it to:

* Bootstrap an `insforge.toml` from a project you've been configuring through the dashboard.
* Diff hand-edits against current backend state by exporting to a temporary file and comparing.
* Snapshot config before a risky change so you can re-apply the snapshot if you need to roll back.

The file written by `export` is the same shape the CLI expects from `apply`, so round-tripping is supported.

Without `--force`, `export` refuses to overwrite an existing file in interactive mode and surfaces an `OUTPUT_EXISTS` error in `--json` mode.

## Secret references

`auth.smtp.password` and any other sensitive field can be expressed as `env(VAR_NAME)` instead of a literal value:

```toml theme={null}
[auth.smtp]
password = "env(SENDGRID_API_KEY)"
```

At apply time the CLI reads `SENDGRID_API_KEY` from the local environment, validates it's present, and sends the resolved value to the backend. The TOML itself never contains the secret, so it can be committed.

This is what lets one `insforge.toml` apply cleanly to multiple environments: the dev and prod backends differ only in *which* `SENDGRID_API_KEY` is in scope when you run `apply`.

`env(...)` refs in a TOML that's the target of `apply` re-send the resolved password on every run. That is the only way the CLI can tell the backend "the secret may have rotated, please update." Fields without an `env(...)` ref are treated as preserve-existing.

## When to use this

* **Version control for project config.** Redirect URLs, sign-up policy, password policy, email verification mode, SMTP, storage upload size, and retention windows live in a file your team reviews via PR.
* **Multi-environment parity.** One TOML, applied to dev, staging, and prod, keeps the supported project settings aligned everywhere. Environment-specific values (subdomain, SMTP credentials) flow through `--project-id` overrides and `env(...)` refs.
* **CI-driven config changes.** Run `config apply --auto-approve --json` from your deploy pipeline. Combine with `config plan` as a PR check so reviewers see what the merge will change in prod.
* **Disaster recovery.** A committed `insforge.toml` is a known-good config snapshot. Re-apply it after restoring a project to bring auth, SMTP, storage, retention, and deployment settings back to the expected shape in seconds.
* **Self-hosted and local OSS development.** Run `npx @insforge/cli link --api-base-url http://localhost:7130 --api-key <local-key>` against a docker-compose stack, then point the CLI's config commands at your local OSS instance the same way you'd point at cloud.

## Troubleshooting

**`Refusing to apply in --json mode without --auto-approve or --yes`.** The CLI never silently applies changes in non-interactive runs. Pass `--auto-approve` (or `-y`) explicitly.

**`your backend doesn't expose <section>`.** The linked backend is on a version that doesn't have the relevant API yet. The rest of your changes still applied. Upgrade the backend (or wait for the next release) to apply that section.

**`env(...)` reference resolves to nothing.** The CLI aborts before any API call when a referenced env var is missing. Set the variable in your shell or your CI's secret store and re-run.

**`Slug is already taken`.** `deployments.subdomain` conflicts with another project's subdomain on the same backend. Pick a different value.

## Related

* [CLI harness](/agent-native/cli-harness): the full command surface an agent drives
* [Deployment security guide](/deployment/deployment-security-guide): hardening a self-hosted backend after deploy