@supatent/cli

Sync schemas and content between your local filesystem and Supatent CMS.

• File-based workflow -- Edit schemas and content as local JSON files using any editor, AI agent, or script
• Three-way reconciliation -- Detects conflicts when both local and remote have changed since last sync
• Bidirectional sync -- Pull remote changes, push local changes, with automatic conflict detection
• Dev mode -- Continuous sync with file watching and WebSocket subscriptions for real-time collaboration
• AI-first design -- Validation status JSON, machine-readable output, non-interactive modes

Installation

# Run directly with npx (recommended)
npx @supatent/cli <command>

# Or install globally
npm install -g @supatent/cli

Quick Start

# 1. Initialize in your project directory
npx @supatent/cli init

# 2. Pull existing content from the CMS
npx @supatent/cli pull

# 3. Edit files in .supatent/schema/ and .supatent/content/

# 4. Check what changed
npx @supatent/cli status

# 5. Push changes back to the CMS
npx @supatent/cli push

Commands

| Command | Description | |---------|-------------| | init | Initialize Supatent in the current directory | | pull | Download schemas and content with three-way reconciliation | | push | Upload local changes with conflict detection | | status | Show changes between local files and remote CMS | | validate | Validate local files against JSON Schema rules | | dev | Start continuous bidirectional sync | | merge | Resolve conflicts between local and remote versions |

All commands support --help for full option details.

Dev Mode

npx @supatent/cli dev

Dev mode provides continuous bidirectional sync:

• File watching -- Detects local changes and pushes them automatically
• WebSocket subscription -- Receives remote changes in real-time via Convex WebSocket
• Validation -- Validates files before pushing, skips invalid files
• Conflict detection -- Warns about conflicts in real-time

Use --no-pull for push-only mode or --no-watch for pull-only mode.

Configuration

Created by init at .supatent/config.json:

{
  "apiUrl": "https://your-deployment.convex.cloud",
  "projectSlug": "my-project"
}

Environment Variables

• SUPATENT_API_KEY -- API key for authentication (recommended for CI/CD)
• CONVEX_URL -- Default Convex deployment URL

For AI Agents

The CLI is designed for AI agent workflows with machine-readable output and non-interactive modes.

# 1. Setup (once per project)
export SUPATENT_API_KEY="sp_live_..."
npx @supatent/cli init --api-url https://your-deployment.convex.cloud --project my-project -y

# 2. Get current content
npx @supatent/cli pull --force

# 3. Edit .supatent/schema/*.json and .supatent/content/*/*.json

# 4. Validate changes (exit code 0 = valid, 1 = errors)
npx @supatent/cli validate

# 5. Push changes
npx @supatent/cli push --force

# Note: Agents can only modify draft content, not publish

Validation Status File

After validation, results are written to .supatent/.validation-status.json with actionable error messages, line/column numbers, and field paths for programmatic consumption.

Machine-Readable Output

• Use --json with status and validate for structured output
• Use -y or --force to skip interactive prompts
• Use --theirs or --mine with merge for non-interactive conflict resolution

Documentation

Full documentation available at supatent.ai/docs.

Requirements

• Node.js >= 20.0.0
• A Supatent project with API access

License

MIT