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

# Forms

> Define forms as JSON, push them with the CLI, and read submissions from the terminal.

Contact, signup, and feedback forms are defined as JSON, registered with the CLI, and rendered from a generated, validated client. Submissions are captured server-side — never hand-roll fetch or validation.

## The flow

<Steps>
  <Step title="Write the form JSON">
    Create `src/forms/{name}.json` — kebab-case filename, e.g. `contact-us.json` — with the fields you need.
  </Step>

  <Step title="Register it">
    ```bash theme={null}
    fimo forms push contact-us
    ```

    This creates the form, obtains its `id`, and patches it back into the JSON file. **Register before writing app code** that depends on the form, or the generated client won't exist and the runtime fetch 404s.
  </Step>

  <Step title="Render it">
    A pre-build step generates `src/forms/contact-us.ts` (a Zod schema + a `submitContactUs` helper). Import from `@/forms/contact-us` in your React component.
  </Step>
</Steps>

## Form commands

```bash theme={null}
fimo forms push [formName]       # push JSON to the API; patches id back. Omit the name to push all.
fimo forms list                  # list registered forms
fimo forms get <id>              # get a single form
fimo forms delete <id>           # delete a form
```

<Note>
  The form JSON spec, the generated Zod schema, and the `submitX` helper signature are part of the project's `fimo` package surface. Load the project `fimo` skill before writing form JSON or the React component. Notification recipients are configured in Fimo Studio, not the CLI.
</Note>

## Read submissions

Once the form is live and people have filled it out, inspect submissions from the terminal:

```bash theme={null}
fimo forms submissions list <formIdOrName> [--limit 50] [--search "<q>"] [--sort asc|desc]
fimo forms submissions get   <formIdOrName> <submissionId>
fimo forms submissions stats <formIdOrName>
```

`<formIdOrName>` accepts the form's UUID or its `name`. `list` returns newest-first by default; `search` matches submission contents server-side. All three are read-only — submissions are created only when a visitor submits the published site's form. For bulk export or older submissions, use Studio.

## What's next

<Columns cols={3}>
  <Card title="Content & CMS" icon="database" href="/docs/cli/content">
    Model structured content.
  </Card>

  <Card title="Labels, locales & i18n" icon="language" href="/docs/cli/labels">
    Localize form copy with `t()`.
  </Card>

  <Card title="Deploy & publish" icon="cloud-arrow-up" href="/docs/deploy/overview">
    Ship the form to production.
  </Card>
</Columns>