CLI Overview

Overview

The holydocs CLI is the main developer tool for HolyDocs. It handles local project setup, previewing, validation, deployment, OpenAPI generation, and migrations from other docs platforms.

Installation

bash
npm install -g @holydocs/cli

See Installation for other package manager options and system requirements.

Commands

Project Setup

Command	Description
holydocs init	Scaffold a new local docs project
holydocs new	Create a new documentation page
holydocs migrate	Import content from Mintlify, Docusaurus, GitBook, ReadMe, Confluence, or Notion

Development

Command	Description
holydocs dev	Start the local preview server with hot reload
holydocs build	Generate a static HTML build
holydocs deploy	Trigger a HolyDocs deployment
holydocs status	Check recent deployments or inspect one deployment
holydocs api	Make authenticated requests to the HolyDocs management API

Validation

Command	Description
holydocs check	Validate the local config file and navigation references
holydocs links	Scan for broken internal links
holydocs openapi-check	Validate an OpenAPI specification

API Reference

Command	Description
holydocs generate	Generate API reference pages from an OpenAPI spec

Authentication

Command	Description
holydocs login	Authenticate with HolyDocs
holydocs logout	Clear stored credentials
holydocs whoami	Show the current stored auth state

Global Flags

These flags work on the top-level holydocs command:

Flag	Short	Description
--help	-h	Show help for the command
--version	-V	Print the CLI version

Per-command flags vary. The most common patterns are:

Pattern	Where it appears
-d, --dir <path>	dev, build, check, init, links, new, generate, migrate
-p, --project <id>	deploy, status
-b, --branch <name>	deploy
--json <json>	api post, api put, api patch, api delete
--api-key <key>	login; also used by migrate readme
--no-browser	login
--no-wizard	login
--api <url>	login

Authentication

The default auth flow is browser-based:

bash
holydocs loginholydocs whoamiholydocs logout

holydocs login opens app.holydocs.com/device, you approve the one-time device code, and the CLI stores the issued API key in ~/.holydocs/config.json.

For CI or other headless environments, you have two options:

bash
# Persist the key locallyholydocs login --api-key hd_xxxxxxxxxxxxxxxxxxxx# Or use ephemeral env vars and skip login entirelyexport HOLYDOCS_API_KEY=hd_xxxxxxxxxxxxxxxxxxxxexport HOLYDOCS_PROJECT=proj_abc123holydocs deploy --no-watch

See holydocs login for the full device-flow details.

Project and Config Resolution

For file-based commands like dev, build, check, and links, the CLI looks for a project root in this order:

1. The directory passed via --dir <path>
2. The current working directory
3. Parent directories containing docs.json, docs.yaml, docs.yml, or mint.json

mint.json is detected for Mintlify compatibility during migration.

For API-backed commands:

1. deploy and status resolve the project from --project, then HOLYDOCS_PROJECT, then local config
2. API auth is resolved from environment variables first, then ~/.holydocs/config.json

Environment Variables

Variable	Read by	Description
HOLYDOCS_API_KEY	API-backed commands like deploy and status	Override the saved API key without writing to local config
HOLYDOCS_API_URL	API-backed commands	Override the API base URL. Default: https://api.holydocs.com
HOLYDOCS_PROJECT	deploy, status	Provide a default project ID
HOLYDOCS_DASHBOARD_URL	login onboarding output	Override the dashboard URL shown in the wizard
CI	login	Prevent the browser from being opened automatically

Quick Reference

bash
# Authenticateholydocs login# Scaffold a projectholydocs init# Start local previewholydocs dev# Validate configholydocs check# Check linksholydocs links# Build static HTMLholydocs build --out dist# Generate API reference pagesholydocs generate openapi.yaml --output api-reference# Deployholydocs deploy# Check deployment statusholydocs status# Migrate from Mintlifyholydocs migrate mintlify