Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@supatent/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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