Quickstart

Prerequisites

• Node.js 18 or later
• A terminal
• 5 minutes

1. Install

npm install -g @agentsforms/cli
# or with pnpm
pnpm add -g @agentsforms/cli

Verify:

agentsforms --version

2. Initialize a project

bash

agentsforms init

Expected output:

✓ Created agentsforms.config.json
✓ Created forms/contact.json

Next: validate your first form
    agentsforms forms validate forms/contact.json

This creates:

• agentsforms.config.json — project config (apiUrl, project name)
• forms/contact.json — a sample form you can edit

3. Define a form

Edit forms/contact.json or create a new one. Here is a complete example:

{
  "name": "Contact form",
  "slug": "contact",
  "description": "Capture inquiries from the generated website.",
  "delivery": {
    "type": "email",
    "to": "[email protected]"
  },
  "fields": [
    {
      "id": "email",
      "label": "Email",
      "type": "email",
      "required": true
    },
    {
      "id": "name",
      "label": "Name",
      "type": "text",
      "required": true
    },
    {
      "id": "message",
      "label": "How can we help?",
      "type": "textarea",
      "required": true
    }
  ],
  "settings": {
    "submitLabel": "Send message",
    "successMessage": "Thanks — your message was sent."
  }
}

Field reference

Field property	Required	Description
id	yes	Stable identifier. Must start with a letter; only [a-zA-Z0-9_.-]; max 64 chars. Must be unique within the form.
label	yes	Human-readable label shown to the user.
type	yes	One of: text, textarea, email, url, number, boolean, date, select, multi_select, checkbox, radio, hidden, file.
required	no	Defaults to false.
description	no	Helper text shown below the field.
agentHint	no	Natural-language hint for agents about how to fill this field.
options	conditional	Required for select, multi_select, radio. Array of { label, value }.
defaultValue	no	Prefill value.
hidden	no	Hide from the human-facing form (agent-only field).

Tip

For the complete field schema reference including settings properties and validation rules, see Form Schema Reference →

4. Validate a form

bash

agentsforms forms validate forms/contact.json

On success:

✓ Form schema is valid

  Name:   Contact form
  Slug:   contact
  Fields: 3

Next: create the form endpoint with email delivery
    agentsforms forms create contact --email [email protected]

On failure:

✗ Invalid form schema — 2 error(s)

  fields.0.id      Field id must start with a letter and contain only [a-zA-Z0-9_.-] (max 64 chars).
  fields.1.options select fields require at least one option.

Fix the above and re-run:
  agentsforms forms validate forms/contact.json

5. Create a form endpoint

bash

agentsforms forms create contact --email [email protected]

Expected output:

✓ Form backend created

  Name:   Contact form
  Slug:   contact
  ID:     form_abc123
  Endpoint: https://api.agentsforms.com/v1/forms/contact/submissions
  Delivery: email → [email protected]
  Hosted preview: https://forms.agentsforms.com/contact

Next: POST your frontend form to the endpoint above

6. Wire the frontend POST

Your agent should keep the form UI in the generated app and POST answers to AgentsForms.

async function submitContactForm(values: {
  name: string;
  email: string;
  message: string;
}) {
  const response = await fetch('https://api.agentsforms.com/v1/forms/contact/submissions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      source: 'site',
      answers: values
    })
  });

  if (!response.ok) {
    throw new Error('Form submission failed');
  }

  return response.json();
}

Expected success response:

{
  "submission": {
    "id": "sub_abc123",
    "status": "accepted",
    "source": "site"
  }
}

Next:

1. Add the generated form component to your site.
2. Submit a test response from the browser.
3. Check [email protected] for the email.

Need zero UI? Use the hosted preview URL as a secondary path.

7. List your forms

agentsforms forms list

ID          SLUG               ENDPOINT                                      SUBMISSIONS   UPDATED
form_abc123 contact            /v1/forms/contact/submissions                  0             2026-06-23

For machine-readable output:

agentsforms forms list --json

8. API-first by default

The generated frontend calls the submission API directly. The CLI and API share the same schema.

Validate a form via API

curl -X POST http://localhost:8787/v1/forms/validate \
  -H "Content-Type: application/json" \
  -d @forms/contact.json

Response (200):

{ "ok": true, "form": { "name": "Contact form", "slug": "contact", "..." : "..." } }

Response (422):

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid form definition",
    "details": [
      { "path": "fields.0.id", "code": "invalid_string", "message": "..." }
    ]
  }
}

---

Complete first flow (copy-paste)

bash

# 1. Install
npm install -g @agentsforms/cli

# 2. Scaffold
agentsforms init

# 3. Edit the example form
#    (open forms/contact.json in your editor)

# 4. Validate
agentsforms forms validate forms/contact.json

# 5. Create
agentsforms forms create contact --email [email protected]

# 6. Publish
agentsforms forms deploy contact

---

Tips

• Every command accepts --json for structured output (useful for agents and scripts).
• forms validate accepts a file path. Pipe via stdin with --stdin:

  cat forms/*.json | agentsforms forms validate --stdin

• Exit codes: 0 = success, non-zero = failure. Safe for CI.
• All errors go to stderr; success to stdout. Safe for piping.
• Config precedence: CLI flags > env vars > project config > global config.