formsubmit-cli

The agentic form backend for static websites. One command, you get a working form.

formsubmit-cli is the official CLI for FormSubmit — a form backend for static sites. Built for vibe coders and AI agents (Claude Code, Cursor, Replit, Bolt, v0, ChatGPT, Lovable): every read command supports --json, every error exits non-zero, and nothing is interactive that doesn't have to be.

30 seconds

npx formsubmit-cli init

Walks you through login (browser pops, you click "Authorize"), creates a form, and prints a copy-paste HTML snippet pointed at FormSubmit. Drop it into any static site and you're done.

<form action="https://app.formsubmit.site/f/<your-id>" method="POST">
  <input name="name" required>
  <input name="email" type="email" required>
  <textarea name="message" required></textarea>
  <button type="submit">Submit</button>
</form>

Why this exists

Most form backends ask you to:

1. Sign up in a browser
2. Click around to create a form
3. Copy a form ID from a dashboard
4. Paste it into your HTML

That works fine for a human typing in a terminal — but an AI agent scaffolding a static site hits friction at every step. formsubmit-cli collapses all four into a single shell command an agent can run as a tool call.

Install

npm install -g formsubmit-cli
# or, never install — let npx grab it each time
npx formsubmit-cli --help

Node 18+. No native deps. ~30 KB unpacked.

Commands

Command	What it does
formsubmit login	Browser device-code auth. Token saved to ~/.formsubmit/config.json (mode 0600).
formsubmit login --token fs_live_…	Skip the browser — paste a token. Useful in CI / containers.
formsubmit logout	Forget the stored token.
formsubmit whoami	Print the account behind the current token.
formsubmit init	Interactive — creates a form and prints HTML.
formsubmit forms list	List forms. --json for agents.
formsubmit forms create --name "Contact"	Create a form. Flags: --description, --redirect, --notify.
formsubmit forms show <id>	Form settings + endpoint URL.
formsubmit forms update <id> --notify / --no-notify	Toggle email notifications.
formsubmit submissions list <id>	Newest first. --limit, --offset, --include-spam, --json.
formsubmit submissions export <id>	CSV to stdout. Pipe it anywhere.
formsubmit credits	Show balance.
formsubmit credits buy	Open the checkout page.
formsubmit snippet <id>	Print HTML for that form. --fields name,email,company,message.

For AI agents

Three guarantees:

1. Every read command supports --json. Output is a stable shape — safe to parse with jq.
2. When --json is set, only JSON goes to stdout. Progress logs go to stderr.
3. Errors exit non-zero with a message on stderr. HTTP 401 ("login") and 402 ("buy credits") are translated into hints that mention the right next command.

Canonical agent recipe

# 1. ensure auth
formsubmit whoami --json || formsubmit login

# 2. check credits — bail with a helpful error if zero
CREDITS=$(formsubmit credits --json | jq -r .availableCredits)
[ "$CREDITS" -le 0 ] && { echo "Run: formsubmit credits buy"; exit 2; }

# 3. create the form
FORM_JSON=$(formsubmit forms create --name "Contact" --json)
FORM_ID=$(echo "$FORM_JSON" | jq -r .id)
ENDPOINT=$(echo "$FORM_JSON" | jq -r .endpoint)

# 4. drop the snippet into the user's site
formsubmit snippet "$FORM_ID" > contact-form.html

echo "Form ready at $ENDPOINT"
echo "View submissions: formsubmit submissions list $FORM_ID"

Discovery files

FormSubmit publishes two discovery endpoints for agents that crawl:

• /llms.txt — short human + agent summary
• /.well-known/formsubmit.json — machine descriptor (capabilities, install command, doc URLs)

Configuration

The CLI saves config at ~/.formsubmit/config.json with mode 0600. Three env vars override it:

Variable	Effect
FORMSUBMIT_API_TOKEN	Use this Bearer token. Overrides the saved one.
FORMSUBMIT_API_BASE	API base URL. Default https://app.formsubmit.site.
FORMSUBMIT_CONFIG_DIR	Alternate config dir. Default ~/.formsubmit.

Pricing

Credit-based. 1 credit = 1 submission. Email notifications cost +1 credit per submission. Spam-flagged submissions are not charged. 100 credits cost $10. Credits never expire.

Links

• 🌐 Website
• 📚 CLI docs
• 🤖 Agent guide
• 🐛 Report a bug

License

MIT © FormSubmit