Every OpenCX project has an opencx.json file in the project root. It is created automatically by opencx auth login or opencx content init.
Add a $schema key pointing to the CLI's JSON Schema for editor autocomplete and validation:
json
{
"$schema": "./node_modules/@opencx/cli/schemas/opencx-config.schema.json",
...
}
Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
help_center_id | string | Yes | -- | The ID of the help center this project syncs with. |
content_dir | string | No | "docs" | Relative path to the directory containing your content files. |
api_url | URL string | No | "https://api.open.cx" | Base URL of the OpenCX API. Override for self-hosted instances. |
dashboard_url | URL string | No | -- | URL of the OpenCX dashboard. Used for generating links. |
provider | string | No | -- | Content provider identifier. |
categories | object | No | -- | Category metadata keyed by path (e.g. "getting-started", "billing"). Each value: { "name": string, "description"?: string, "icon"?: string }. When missing for a path, the category name is derived from the directory name. |
Example
json
{
"$schema": "./node_modules/@opencx/cli/schemas/opencx-config.schema.json",
"help_center_id": "hc_abc123",
"content_dir": "docs",
"api_url": "https://api.open.cx",
"dashboard_url": "https://app.open.cx",
"categories": {
"getting-started": { "name": "Getting Started" },
"billing": {
"name": "Billing & Payments",
"description": "Invoices and subscriptions",
"icon": "credit-card"
}
}
}
How It Is Created
Running opencx auth login or opencx content init writes this file to your current working directory. The help_center_id is selected interactively during setup, and the remaining fields are populated with sensible defaults.
Validation
The CLI validates opencx.json on every command that reads it. If required fields are missing or values are malformed, you will see a clear error message pointing to the invalid field. The api_url and dashboard_url fields must be valid URLs.