@opencx/cli

CLI for managing OpenCX help center content as code.

Install

npm install -g @opencx/cli

Or with Bun / pnpm:

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

Use without installing:

npx @opencx/cli auth login

Quick Start

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

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.

opencx content init

content check

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

opencx content check
opencx content check --json

content diff

Show what would change without pushing.

opencx content diff
opencx content diff --json

content push

Push local content to OpenCX.

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.

opencx content pull

content gate

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

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.

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.

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.

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

Article frontmatter

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

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

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 >= 1.0.

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:

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

Or run them individually:

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:

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