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

# Environments

> Git-shaped, isolated environments — each with its own database, sandbox, and preview — with a workflow that mirrors git.

A Fimo **environment** is a multi-surface clone of your project: a git branch **plus** its own database branch, sandbox, preview URL, and asset storage. The CLI mirrors `git` command shapes, so the workflow transfers directly — same verbs, multi-surface semantics.

Every project starts with one environment, `main`. You create more for feature work, preview them in isolation, then merge back and publish.

<Note>
  **Branch environments are in beta.** The CLI surface is available for early workflows, but not every command or cross-surface merge path is guaranteed to work reliably yet.
</Note>

## How commands pick their target

The single most important rule: project-scoped commands target the environment of your **current git branch**. On branch `feat/seo`, `fimo deploy`, `fimo status`, and `fimo entries list` all operate on the `feat/seo` environment. The CLI prints a one-line banner telling you which environment it resolved.

```bash theme={null}
fimo --env <name> <command>   # peek at another environment for one command (doesn't switch)
```

`main` is the default and can't be deleted. `release/*` environments are read-only tags produced by publishing, and `prod` is protected — updated by publishing, never by pushing.

## Commands

| Command                 | git analogue   | What it does                                                       |
| ----------------------- | -------------- | ------------------------------------------------------------------ |
| `fimo branch`           | `git branch`   | List environments (`-v` adds preview URLs).                        |
| `fimo branch <name>`    | `git branch`   | Create an environment; provisions DB + sandbox + preview + assets. |
| `fimo checkout <name>`  | `git checkout` | Switch environments (`-b` creates + switches).                     |
| `fimo switch <name>`    | `git switch`   | Switch to an existing environment.                                 |
| `fimo pull`             | `git pull`     | Sync the current env's data from its parent.                       |
| `fimo diff [from] [to]` | `git diff`     | Two-env diff across all surfaces.                                  |
| `fimo status`           | `git status`   | Multi-surface status vs the parent.                                |
| `fimo merge <from>`     | `git merge`    | Merge another environment in (interactive conflict resolver).      |
| `fimo publish`          | —              | Tag a `release/<version>` and trigger the prod swap.               |

`status`, `diff`, and `merge` reason over seven per-env surfaces: `code`, `schemas`, `content`, `translations`, `assets`, `forms`, and `activations`.

## A PR-style flow

```bash theme={null}
fimo checkout -b feat/seo        # branch off main: git branch + environment provisioned
# …generate / edit code, schemas, content…
fimo deploy -m "feat: seo pass"  # deploy a preview of the feat/seo environment
fimo status                      # see what changed vs main, surface by surface
fimo checkout main               # back to main
fimo merge feat/seo              # merge the environment back in
fimo publish --version 1.4.0     # tag a release + prod swap
fimo branch -d feat/seo          # tear down the feature environment
```

<Warning>
  Use `fimo checkout -b`, not raw `git checkout -b` — plain git creates the branch but **not** the environment's database, sandbox, or preview. Merging directly onto `main` is gated; prefer merging on a branch, then publishing.
</Warning>

## What's next

<Columns cols={3}>
  <Card title="Preview vs production" icon="eye" href="/docs/environments/preview-vs-production">
    On-demand previews and going live.
  </Card>

  <Card title="Version history" icon="clock-rotate-left" href="/docs/environments/version-history">
    Restore an earlier state.
  </Card>

  <Card title="Deploy & publish" icon="cloud-arrow-up" href="/docs/deploy/overview">
    The deploy pipeline.
  </Card>
</Columns>