formdata.dev

CLI Setup

The formdata-dev CLI lets you create accounts, manage forms, and configure destinations from your terminal. It requires no global installation.

Installation

The CLI runs via npx -- no global install is needed:

npx formdata-dev --version

Expected output:

0.2.0

Create an Account

  1. Run the init command to create your account interactively:
npx formdata-dev init
  1. Enter the required details when prompted:
formdata.dev — Create Account ────────────────────────────── Organization name: Acme Corp Owner email: admin@acme.com Subdomain slug (e.g. "acme" for acme.formdata.dev): acme Creating account... Account Created ──────────────── Organization: Acme Corp Subdomain: acme.formdata.dev Secret key: sk_a1b2c3d4e5f6... Credentials saved to /home/you/.config/formdata/credentials Warning: Your secret key is shown only once. It is stored in the credentials file.
  1. The CLI will then prompt you to create your first form and add a destination.
WARNING

Your secret key (sk_...) is displayed only once during account creation. It is saved to your credentials file automatically, but keep a backup in a secure location.

Credential Storage

Credentials are stored as JSON at:

~/.config/formdata/credentials

The file contains:

{
  "secretKey": "sk_a1b2c3d4e5f6...",
  "apiUrl": "https://api.formdata.dev",
  "organizationName": "Acme Corp",
  "slug": "acme"
}

File permissions are set to 0600 (owner read/write only) automatically on Unix systems.

TIP

If you set the XDG_CONFIG_HOME environment variable, the CLI respects it and stores credentials at $XDG_CONFIG_HOME/formdata/credentials instead.

CLI Commands

Account

Command Description
npx formdata-dev init Create account and store credentials
npx formdata-dev status Account overview with all forms and destinations
npx formdata-dev keys rotate Rotate secret key (invalidates the old key)

Forms

Command Description
npx formdata-dev forms list List all forms
npx formdata-dev forms create Create a new form (interactive)
npx formdata-dev forms get <id> Show form details and destinations
npx formdata-dev forms update <id> Update form settings
npx formdata-dev forms delete <id> Delete a form

Destinations

Command Description
npx formdata-dev destinations list List destinations for a form
npx formdata-dev destinations add Add a destination to a form (interactive)
npx formdata-dev destinations rm <formId> <destId> Remove a destination

Check Your Setup

After initializing, verify everything is configured:

npx formdata-dev status

Expected output:

Account Status ────────────── Organization: Acme Corp Subdomain: acme.formdata.dev API URL: https://api.formdata.dev Forms: 1 total (1 enabled, 0 disabled) Contact Form (contact) — enabled Public key: pk_abcdef1234567890... Endpoint: POST https://api.formdata.dev/v1/f/pk_abcdef1234567890... Destinations: 1 webhook https://hooks.example.com/form

Troubleshooting

Error Cause Fix
Network error: fetch failed Cannot reach api.formdata.dev Check your internet connection and firewall rules
Invalid or expired credentials (401) Secret key is wrong or was rotated Run npx formdata-dev init to set up again, or npx formdata-dev keys rotate if you still have a valid key
slug already taken (409) Another account already uses that subdomain slug Choose a different slug value
No credentials found Missing credentials file Run npx formdata-dev init to create an account
Not found (404) Form or destination ID does not exist Run npx formdata-dev forms list to find valid IDs
Required. Please enter a value. A required prompt was left blank Enter a non-empty value for the field
INFO

On Windows, the chmod 0600 call for the credentials file is a no-op. Make sure your user profile directory has appropriate access controls.

ON THIS PAGE