CLI reference

formsubmit is the agentic CLI for FormSubmit. Designed so an AI agent (Claude Code, Cursor, Replit, Bolt) can do everything a human can: create forms, scaffold HTML, list submissions, manage credits.

Install

$ npm install -g formsubmit-cli
# or, run it on the fly
$ npx formsubmit-cli --help

Authenticate

$ formsubmit login

Opens a browser to authorize this machine via a device-code flow. The CLI saves the API token at ~/.formsubmit/config.json (mode 0600). To skip the browser (CI, containers), pass a token directly:

$ formsubmit login --token "fs_live_…"
# or via env
$ export FORMSUBMIT_API_TOKEN=fs_live_…

Quick start

# interactive
$ formsubmit init

# non-interactive (for agents)
$ FORM_ID=$(formsubmit forms create --name "Contact" --json | jq -r .id)
$ formsubmit snippet "$FORM_ID" > contact-form.html

All commands

$ formsubmit login

Authorize this machine via the browser device-code flow. Use --token fs_live_… to skip the browser (CI / containers).

$ formsubmit logout

Remove the stored token from ~/.formsubmit/config.json.

$ formsubmit whoami

Print the account associated with the current token. --json available.

$ formsubmit init

Interactive — creates a form and prints the HTML. Pass --name to skip prompts.

$ formsubmit forms list

List your forms. --json for agents.

$ formsubmit forms create --name "X"

Create a form. Flags: --description, --redirect, --notify, --json.

$ formsubmit forms show <id>

Show one form: settings, endpoint URL, notify state.

$ formsubmit forms update <id> --notify / --no-notify

Toggle email notifications on the form.

$ formsubmit submissions list <id>

Newest first. --limit, --offset, --include-spam, --json.

$ formsubmit submissions export <id>

Stream CSV to stdout. Pipe anywhere.

$ formsubmit credits

Show balance. --json for agents.

$ formsubmit credits buy

Open the checkout page; CLI waits until credits land. --no-wait to fire-and-forget.

$ formsubmit snippet <id>

Print a copy-paste HTML form. --fields name,email,company,message.

Output conventions

  • --json on every read command. Only JSON goes to stdout — progress logs print to stderr.
  • Errors exit non-zero with a one-line message on stderr.
  • Stable field shapes. Agents can pipe through jq without surprises.

Environment overrides

  • FORMSUBMIT_API_TOKEN — Bearer token. Overrides the saved one.
  • FORMSUBMIT_API_BASE — alternate API base URL (default https://app.formsubmit.site).
  • FORMSUBMIT_CONFIG_DIR — alternate config directory (default ~/.formsubmit).
Guide for AI agents → GitHub npm