@gately/cli

Push MDX/Markdown docs from your codebase to your Gately Help Center.

Install

npm install -g @gately/cli

Or use without installing (always runs the latest version):

npx @gately/cli@latest push

Updating:

# Global install
npm update -g @gately/cli

# Or just use npx — always latest, no update needed
npx @gately/cli@latest push

Quick start

# 1. Create config
gately init

# 2. Authenticate
gately login

# 3. Preview
gately push --dry-run

# 4. Push
gately push

Commands

| Command | Description | |---------|-------------| | gately login | Authenticate via browser — picks your project | | gately logout | Remove stored credentials | | gately whoami | Show the currently authenticated project | | gately init | Create a gately.config.json in the current directory | | gately push | Push docs to your help center | | gately push --dry-run | Preview what would be pushed without making changes | | gately push --no-fix | Push without auto-fixing invalid icon names | | gately pull | Pull articles from database to local markdown files | | gately pull --folder blog | Pull only articles from specific folder | | gately pull --overwrite | Overwrite existing local files | | gately pull --no-update-config | Skip updating gately.config.json | | gately sync | Pull navigation structure from help center to local repo | | gately sync --generate-config | Generate suggested config from database structure | | gately sync -o nav.json | Save navigation to custom file | | gately format | Format and clean markdown/MDX files (normalize whitespace, line endings) | | gately format --check | Check if files need formatting without modifying them | | gately validate | Check docs for issues without pushing |

Authentication

gately login

Opens your browser to pick a project. Credentials are stored in ~/.gately/credentials.json.

You can also use an environment variable or config file instead:

export GATELY_API_KEY=gately_sk_live_xxxxxxxx

Priority: config.apiKey → GATELY_API_KEY env var → stored credentials.

Config file

gately.config.json at your repo root:

{
  "openapi": "openapi.json",
  "docs": [
    {
      "path": "docs/**/*.{md,mdx}",
      "folder": {
        "name": "Documentation",
        "icon": "hugeicons:book-open-01",
        "description": "Product documentation"
      },
      "category": {
        "name": "Getting Started",
        "icon": "hugeicons:rocket-01"
      },
      "publish": true
    }
  ],
  "delete": ["old-article-slug", "deprecated-guide"],
  "uncategorized": ["draft-article"]
}

Top-level fields

| Field | Type | Description | |-------|------|-------------| | apiKey | string | API key (or use GATELY_API_KEY env var) | | apiUrl | string | Override API URL (defaults to production) | | docs | array | Doc sources — see below | | openapi | string | Path to OpenAPI spec file for interactive API docs |

Doc source fields

| Field | Type | Description | |-------|------|-------------| | path | string | string[] | Glob pattern(s) relative to config file | | folder | string | NavItem | Folder (max 3 per project) | | category | string | NavItem | Category inside the folder | | subcategory | string | NavItem | Subcategory nested under category | | publish | boolean | Publish immediately (default: false = draft) |

NavItem

Each level accepts a plain string (name only) or a full object:

{
  "name": "API Reference",
  "icon": "hugeicons:api",
  "description": "Full REST API docs",
  "display_order": 1,
  "slug": "api-reference"
}

| Field | Type | Description | |-------|------|-------------| | name | string | Display name (required) | | icon | string | Hugeicons icon (e.g. hugeicons:api) | | description | string | Short description | | display_order | number | Sort order (lower numbers appear first) | | slug | string | Custom URL-friendly slug (auto-generated from name if omitted) | | sidebar_title | string | Shorter label shown in sidebar instead of full name |

Missing items are created automatically. Icons, display_order, and slugs are updated if they change.

Hierarchy

Folder  (max 3 per project)
└── Category
    └── Subcategory
        └── Article

Example with subcategories:

{
  "path": "sdk/javascript.mdx",
  "folder": "Documentation",
  "category": { "name": "SDK & Integrations", "icon": "hugeicons:code-circle" },
  "subcategory": { "name": "JavaScript SDK", "icon": "hugeicons:java-script" },
  "publish": true
}

Frontmatter

Per-article control via frontmatter:

---
title: Getting Started
slug: getting-started
sidebar_title: Quick Start
icon: hugeicons:rocket-01
excerpt: Get up and running in 5 minutes.
publish: true
category: Getting Started
subcategory: Quick Start
display_order: 1
keywords: [guide, tutorial, quickstart]
meta_title: Getting Started with Gately
meta_description: Learn how to get up and running with Gately in 5 minutes
og_image_url: https://example.com/og-image.png
show_toc: true
---

| Field | Description | |-------|-------------| | title | Falls back to first H1, then filename | | slug | Auto-generated from title if omitted | | sidebar_title | Shorter label shown in the sidebar | | icon | Hugeicons name shown next to article | | excerpt | Short summary, auto-generated if omitted | | publish | Overrides source-level publish setting | | folder | Overrides source-level folder | | category | Overrides source-level category | | subcategory | Overrides source-level subcategory | | display_order | Sort order within category (lower numbers appear first) | | keywords / tags | Array of SEO keywords | | meta_title | SEO title (defaults to title) | | meta_description | SEO description (defaults to excerpt) | | og_image_url | Open Graph image URL for social sharing | | show_toc | Show table of contents (default: true) |

API Documentation

Create interactive API reference documentation with the api field:

---
title: "Login"
api: "POST https://api.usegately.com/api/v1/auth/login"
description: "Authenticate a user with email and password"
---

## Request Body

<ParamField body="email" type="string" required>
  The user's email address
</ParamField>

<ParamField body="password" type="string" required>
  The user's password
</ParamField>

The CLI automatically:

• Extracts the HTTP method (POST)
• Extracts the endpoint path (/api/v1/auth/login)
• Extracts the base URL (https://api.usegately.com)
• Marks the article as api_reference type
• Enables the interactive "Try It" button in your help center

You can also set article_type in the config for entire directories:

{
  "path": "api-reference/**/*.mdx",
  "folder": "API Reference",
  "category": "Authentication",
  "article_type": "api_reference",
  "publish": true
}

Icons

All icons use Hugeicons via Iconify format:

hugeicons:icon-name

Auto-fix

When you run gately push, invalid icon names are automatically fixed in your source files using the best match from the local icon dataset:

✓ fixed icon  hugeicons:rocket-1 → hugeicons:rocket-01  docs/quickstart.md

Use --no-fix to disable this and just report instead.

Validate before pushing

gately validate

Checks all files and reports issues without making any changes:

  docs/quickstart.md ✗ [icon] "hugeicons:flash-1" is not a valid hugeicons icon
    → change to hugeicons:flash

  docs/sdk/javascript.mdx ⚠ [slug] Missing slug — will be auto-generated from title

✓ OpenAPI spec looks good  (42 endpoints)

2 errors  1 warning

gately validate exits with code 1 if there are errors — works in CI.

OpenAPI spec

Add an OpenAPI spec to your config to enable the interactive API reference page in your help center:

{
  "openapi": "openapi.json"
}

The spec (JSON or YAML) is uploaded to Gately on every gately push and served dynamically per project. Users can enter their API key directly in the playground and fire live requests.

gately validate also checks your spec for common issues:

• Missing info.title / info.version
• No servers defined
• No paths defined
• No security schemes

CI/CD

# .github/workflows/docs.yml
name: Sync docs
on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @gately/cli format --check
      - run: npx @gately/cli validate
      - run: npx @gately/cli push
        env:
          GATELY_API_KEY: ${{ secrets.GATELY_API_KEY }}

The format --check command ensures all files are properly formatted before pushing.

Formatting

The CLI includes a formatter to clean and normalize your markdown/MDX files:

# Format all files
gately format

# Check if files need formatting (useful in CI)
gately format --check

The formatter:

• Normalizes line endings to \n
• Removes trailing whitespace
• Removes excessive blank lines (max 2 consecutive)
• Ensures proper spacing around headings, code blocks, and lists
• Ensures single newline at end of file
• Normalizes frontmatter formatting

Run gately format before pushing to ensure clean, consistent content.

How it works

1. Reads gately.config.json to find doc sources
2. Parses frontmatter from each .md / .mdx file
3. Validates icons against local Hugeicons data — auto-fixes invalid names in source files
4. Resolves the Folder → Category → Subcategory hierarchy (creates missing items, updates icons)
5. Upserts articles by slug — creates new ones, updates existing ones
6. Uploads OpenAPI spec if configured

Supported file types

Both .md and .mdx are fully supported. Use glob patterns to match both:

{ "path": "docs/**/*.{md,mdx}" }

MDX components and custom block syntax (callouts, tabs, steps, cards, accordions) are parsed and converted to Gately's rich content format automatically.