Spike Forms CLI

Command-line interface for managing Spike Forms - forms, submissions, projects, and teams.

Installation

npm install -g @spike-forms/cli

Quick Start

# Authenticate via browser
spike login

# Create a form with live preview
spike forms create-page --name "Contact Form" --preview

# Edit and save changes
spike forms save

# List your forms
spike forms list

Authentication

Browser Login (Recommended)

The login command opens your browser to authenticate and automatically saves your API key:

spike login

Options:

• --timeout <seconds> - Set login timeout (default: 120s)
• --no-browser - Display URL instead of opening browser automatically

Manual Configuration

# Set API key directly
spike config set api-key <your-api-key>

# View current config
spike config get api-key

Forms Management

Basic Operations

# List all forms
spike forms list
spike forms list --limit 10 --format json

# Get form details
spike forms get <form-id>

# Create a form
spike forms create --name "Contact Form"

# Update a form
spike forms update <form-id> --name "New Name"
spike forms update <form-id> --is-active false

# Delete a form
spike forms delete <form-id>

Live Preview Workflow

Edit forms locally with instant browser refresh. HTML is stored on the server (S3).

# Edit existing form with live preview (fetches HTML from server)
spike forms edit <form-id>

# Run preview server in background
spike forms edit <form-id> --background

# Save local changes back to server
spike forms save
spike forms save <form-id> --file ./my-form.html

# Stop background preview server
spike forms stop-preview

The preview server:

• Fetches HTML from server (S3) when you start editing
• Watches your local HTML file for changes
• Auto-refreshes the browser via Server-Sent Events
• Runs on http://127.0.0.1 with a dynamic port

Create Form Page (Beta)

Create a new form and generate an HTML template in one command:

# Create form and HTML file (saves to server automatically)
spike forms create-page --name "Contact Form"

# Create and start preview immediately
spike forms create-page --name "Contact Form" --preview

# Save to custom path
spike forms create-page --name "Contact Form" --file ./contact.html

The generated HTML includes:

• Responsive form layout with basic styling
• Form action pointing to your form's submission endpoint (/f/{slug})
• Name, email, and message fields (customize as needed)

Complete Edit Workflow

1. Start editing: spike forms edit <form-id>

   • Fetches HTML from server (S3)
   • Saves to local file (./form.html)
   • Starts live preview server
   • Opens browser

2. Make changes: Edit ./form.html in your editor

   • Browser auto-refreshes on save

3. Save to server: spike forms save

   • Uploads HTML back to server (S3)
   • Dashboard iframe will show updated form

4. Stop preview: Press Ctrl+C or run spike forms stop-preview

Submissions

# List submissions for a form
spike submissions list --form-id <form-id>

# Get submission details
spike submissions get <submission-id>

# Delete a submission
spike submissions delete <submission-id>

Projects & Teams

# Projects
spike projects list
spike projects create --name "Website Forms"
spike projects get <project-id>

# Teams
spike teams list
spike teams create --name "Marketing"
spike teams get <team-id>

AI Agent Integration

Launch OpenCode with Spike Forms knowledge:

# Launch OpenCode (must be installed)
spike agent

# Install OpenCode if not present
spike agent --install

# Use specific model
spike agent --model gpt-4

The agent command installs a skill file that teaches OpenCode about all CLI commands.

Configuration

Config file location: ~/.spike/config.json

# Set values
spike config set api-key <key>
spike config set base-url <url>

# Get values
spike config get api-key
spike config get base-url

Environment Variables

• SPIKE_API_KEY or SPIKE_TOKEN - API key for authentication
• SPIKE_API_URL - Custom API base URL
• SPIKE_DASHBOARD_URL - Custom dashboard URL for login

How It Works

Form HTML Storage

Form HTML templates are stored in S3:

• spike forms edit fetches HTML from API → API fetches from S3 → returns to CLI
• spike forms save uploads HTML to API → API stores in S3
• Dashboard iframe loads HTML from S3 URL stored in form's html_url field

Form Submission Flow

1. User visits form page (HTML served from S3 or embedded)
2. Form action points to /f/{slug} on the Spike API
3. Submissions are stored in database
4. View submissions via CLI or dashboard

Login Flow

1. CLI generates a secure state token
2. Opens browser to dashboard consent page
3. User approves CLI access
4. Dashboard creates API key and redirects to CLI callback
5. CLI saves the API key to config