npm package: @supatent/cli
Description: Sync schemas and content locally with Supatent CMS
Author: Supatent
Latest version: 0.3.1

[![npm version](https://img.shields.io/npm/v/@supatent/cli)](https://www.npmjs.com/package/@supatent/cli)
[![license](https://img.shields.io/npm/l/@supatent/cli)](https://github.com/supatent/supatent/blob/main/LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/supatent/supatent/release.yml?branch=main)](https://github.com/supatent/supatent/actions/workflows/release.yml)

# @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

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

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

## Quick Start

```bash
# 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

```bash
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`:

```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.

```bash
# 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](https://supatent.ai/docs).

## Requirements

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

## License

MIT