npm package: @opencx/cli
Description: CLI for managing OpenCX help center content as code.
Latest version: 0.1.4

# @opencx/cli

CLI for managing OpenCX help center content as code.

## Install

```bash
npm install -g @opencx/cli
```

Or with Bun / pnpm:

```bash
bun install -g @opencx/cli
# or
pnpm add -g @opencx/cli
```

Use without installing:

```bash
npx @opencx/cli auth login
```

## Quick Start

```bash
# 1. Authenticate (opens browser, or use --token for CI)
opencx auth login

# 2. Initialize content directory (pulls existing content)
opencx content init

# 3. Push local content to OpenCX
opencx content push
```

## Commands

### `auth login`

Authenticate with OpenCX. Opens a browser flow by default, or accepts an API key directly.

```bash
opencx auth login                          # Browser flow
opencx auth login --token <key>            # API key (non-interactive)
opencx auth login --api-url http://...     # Custom API URL
opencx auth login --dashboard-url http://… # Custom dashboard URL
```

### `content init`

Initialize content directory and pull existing articles from your help center.

```bash
opencx content init
```

### `content check`

Validate content files locally (frontmatter, slugs, structure).

```bash
opencx content check
opencx content check --json
```

### `content diff`

Show what would change without pushing.

```bash
opencx content diff
opencx content diff --json
```

### `content push`

Push local content to OpenCX.

```bash
opencx content push
opencx content push --yes          # Skip confirmation prompts
opencx content push --dry-run      # Show diff only
opencx content push --json         # Machine-readable output
```

### `content pull`

Pull content from OpenCX into the local directory.

```bash
opencx content pull
```

### `content gate`

CI gate: validate content and check for drift. Exits 1 if content is invalid or out of sync.

```bash
opencx content gate
opencx content gate --json
```

### `content dev`

Start a local preview server for help center content. Runs a mock API and a pre-built help center frontend, with hot-reload on file changes.

```bash
opencx content dev                 # Preview on http://localhost:3333
opencx content dev --port 4000     # Custom preview port
```

## File Structure

### `opencx.toml`

Project configuration, created by `opencx auth login`.

```toml
help_center_id = "hc_..."
content_dir = "docs"
api_url = "https://api.open.cx"        # optional, defaults to production
dashboard_url = "https://platform.open.cx"  # optional
```

### Content directory

```
docs/
  getting-started/
    category.toml          # Category metadata (name, description, icon)
    quick-start.md         # Article file
    installation.md
  advanced/
    category.toml
    configuration.md
```

### `category.toml`

Optional metadata for each category folder. If omitted, the category name is derived from the folder name.

```toml
name = "Getting Started"
description = "Learn the basics"   # optional
icon = "rocket"                    # optional
```

### Article frontmatter

Each `.md` file requires a `title` field. Other fields are optional.

```markdown
---
title: Quick Start Guide
description: Get up and running in 5 minutes
meta_title: Quick Start - MyApp Help Center
meta_description: Step-by-step guide to get started
---

Article content here...
```

### `.opencx-lock.json`

Lock file tracking push state. Commit this to detect content drift in CI.

## CI/CD

Use the `gate` command to block PRs when content is invalid or drifted from the remote.

Set `OPENCX_API_KEY` as a secret (get it from your OpenCX dashboard).

### GitHub Actions

```yaml
name: Content Gate
on: pull_request

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @opencx/cli content gate --json
        env:
          OPENCX_API_KEY: ${{ secrets.OPENCX_API_KEY }}
```

## Development

Prerequisites: [Bun](https://bun.sh) >= 1.0.

```bash
bun install
bun run dev              # Run CLI directly (e.g. bun run dev auth login)
bun test                 # Run tests
bun run check            # Lint
bun run check:fix        # Lint + auto-fix
bun run typecheck        # TypeScript check
```

### Local dev with mock servers

To test the full auth flow without running the backend or dashboard:

```bash
bun run dev:mock         # Start mock API + mock dashboard + run auth login
```

Or run them individually:

```bash
bun run dev:mock-api         # Mock API on :8080
bun run dev:mock-dashboard   # Mock dashboard on :3000
```

### Pointing at local backend/dashboard

Set `api_url` and optionally `dashboard_url` in `opencx.toml` to override the default production URLs:

```toml
api_url = "http://localhost:8080"
dashboard_url = "http://localhost:3000"
```