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/example-form.json

Next: validate your first form
    agentsforms forms validate forms/example-form.json

This creates:

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

3. Define a form

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

{
  "name": "Support Intake",
  "slug": "support-intake",
  "description": "Collect missing info from users for support agents.",
  "fields": [
    {
      "id": "email",
      "label": "Email",
      "type": "email",
      "required": true
    },
    {
      "id": "priority",
      "label": "Priority",
      "type": "select",
      "required": true,
      "options": [
        { "label": "Low",    "value": "low" },
        { "label": "Medium", "value": "medium" },
        { "label": "High",   "value": "high" }
      ]
    },
    {
      "id": "message",
      "label": "What do you need help with?",
      "type": "textarea",
      "required": true
    }
  ],
  "settings": {
    "submitLabel": "Send to agent",
    "successMessage": "Thanks — an agent will continue with this."
  }
}

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/example-form.json

On success:

✓ Form schema is valid

  Name:   Support Intake
  Slug:   support-intake
  Fields: 3

Next: create the form
    agentsforms forms create forms/example-form.json

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/example-form.json

5. Create a form

bash

agentsforms forms create forms/example-form.json

Expected output:

✓ Form created (draft)

  Name:   Support Intake
  Slug:   support-intake
  ID:     form_abc123
  Status: draft

Next: publish it to make it live
    agentsforms forms publish support-intake

6. Publish a form

bash

agentsforms forms publish support-intake

Expected output:

✓ Form published

  Name:        Support Intake
  Form ID:     form_abc123
  Version:     1
  Hosted URL:  https://agentsforms.com/f/support-intake
  API:         https://api.agentsforms.com/v1/forms/form_abc123

Next:
  1. Create a session:  agentsforms sessions create support-intake
  2. Tail submissions:  agentsforms submissions tail support-intake
  3. Add a webhook:     agentsforms webhooks create --url https://your-agent.com/webhook

7. List your forms

agentsforms forms list

ID          SLUG               STATUS      VERSION   SUBMISSIONS   UPDATED
form_abc123 support-intake     published   1         0             2026-06-23

For machine-readable output:

agentsforms forms list --json

8. API (headless)

You can also drive AgentsForms entirely via HTTP. 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/example-form.json

Response (200):

{ "ok": true, "form": { "name": "Support Intake", "slug": "support-intake", "..." : "..." } }

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/example-form.json in your editor)

# 4. Validate
agentsforms forms validate forms/example-form.json

# 5. Create
agentsforms forms create forms/example-form.json

# 6. Publish
agentsforms forms publish example-form

---

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.