generate-form

Generate Form

Take a user's natural language description and convert it into a structured form created automatically on pyform via API.

Step 1: Verify API Key

First check the environment, then fall back to the .env file:

echo "${PYFORM_API_KEY:-NOT_SET}"

If NOT_SET, check .env:

grep '^PYFORM_API_KEY=' .env 2>/dev/null | head -1 | cut -d'=' -f2 | tr -d '"'

If both return empty or NOT_SET, inform the user:

Your pyform API Key is not configured. Run /pyform-setup to connect your account (it only takes a moment).

Then stop.

If a valid key is found (starts with pyf_), keep it in memory and continue. Do not print the key.

Step 2: Design the form

Read the user's description and generate a JSON payload following the schema in references/form-schema.md.

Quick rules

• Start with WELCOME if the form has 3+ questions.
• End with GOODBYE if you started with WELCOME.
• options is mandatory for MULTIPLE_CHOICE, CHECKBOXES, and DROPDOWN.
• Use descriptive, unique ids (e.g., q_satisfaction, q_email).
• Mark required: true only on essential fields.
• Generate context-appropriate welcome and goodbye messages.
• Use isConversational: true for surveys and feedback forms.

Step 3: Send to API

Save the JSON and send it with curl. Substitute the actual key value directly into the header (do not rely on shell variable expansion):

curl -s -w "\n%{http_code}" \
  -X POST https://pyform.app/api/forms \
  -H "Content-Type: application/json" \
  -H "x-api-key: ACTUAL_KEY_VALUE" \
  -d '$JSON_PAYLOAD'

Step 4: Handle response

Code	Action
200	Show: form title, number of questions created, and any unmappedFields.
400	Show error details, fix the JSON, and retry once.
401	Inform: "Your API Key is invalid or has been revoked. Generate a new one in Settings → API Keys and run /pyform-setup again."
402	Inform: "Your pyform subscription is not active. Renew your plan in the dashboard."
500	Inform: server error, try again later.

On success, show a clean, friendly summary. Never show raw JSON to the user.