@spike-forms/cli 0.2.0

package/README.md

@@ -0,0 +1,222 @@
+# Spike Forms CLI
+
+Command-line interface for managing Spike Forms - forms, submissions, projects, and teams.
+
+## Installation
+
+```bash
+npm install -g @spike-forms/cli
+```
+
+## Quick Start
+
+```bash
+# 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:
+
+```bash
+spike login
+```
+
+Options:
+- `--timeout <seconds>` - Set login timeout (default: 120s)
+- `--no-browser` - Display URL instead of opening browser automatically
+
+### Manual Configuration
+
+```bash
+# Set API key directly
+spike config set api-key <your-api-key>
+
+# View current config
+spike config get api-key
+```
+
+## Forms Management
+
+### Basic Operations
+
+```bash
+# 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).
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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`
+
+```bash
+# 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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }