> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

The HolyDocs CLI lets you scaffold, preview, validate, migrate, and deploy docs projects from the terminal.

## 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](/installation) for other package manager options and system requirements.

## Commands

### Project Setup

| Command | Description |
|---|---|
| [`holydocs init`](/cli/init) | Scaffold a new local docs project |
| [`holydocs new`](/cli/new-page) | Create a new documentation page |
| [`holydocs migrate`](/cli/migrate) | Import content from Mintlify, Docusaurus, GitBook, ReadMe, Confluence, or Notion |

### Development

| Command | Description |
|---|---|
| [`holydocs dev`](/cli/dev) | Start the local preview server with hot reload |
| [`holydocs build`](/cli/build) | Generate a static HTML build |
| [`holydocs deploy`](/cli/deploy) | Trigger a HolyDocs deployment |
| [`holydocs status`](/cli/status) | Check recent deployments or inspect one deployment |
| [`holydocs api`](/cli/api) | Make authenticated requests to the HolyDocs management API |

### Validation

| Command | Description |
|---|---|
| [`holydocs check`](/cli/check) | Validate the local config file and navigation references |
| [`holydocs links`](/cli/links) | Scan for broken internal links |
| [`holydocs openapi-check`](/cli/openapi-check) | Validate an OpenAPI specification |

### API Reference

| Command | Description |
|---|---|
| [`holydocs generate`](/cli/generate) | Generate API reference pages from an OpenAPI spec |

### Authentication

| Command | Description |
|---|---|
| [`holydocs login`](/cli/login) | Authenticate with HolyDocs |
| [`holydocs logout`](/cli/login#holydocs-logout) | Clear stored credentials |
| [`holydocs whoami`](/cli/login#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 login
holydocs whoami
holydocs 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 locally
holydocs login --api-key hd_xxxxxxxxxxxxxxxxxxxx

# Or use ephemeral env vars and skip login entirely
export HOLYDOCS_API_KEY=hd_xxxxxxxxxxxxxxxxxxxx
export HOLYDOCS_PROJECT=proj_abc123
holydocs deploy --no-watch
```

See [`holydocs login`](/cli/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
# Authenticate
holydocs login

# Scaffold a project
holydocs init

# Start local preview
holydocs dev

# Validate config
holydocs check

# Check links
holydocs links

# Build static HTML
holydocs build --out dist

# Generate API reference pages
holydocs generate openapi.yaml --output api-reference

# Deploy
holydocs deploy

# Check deployment status
holydocs status

# Migrate from Mintlify
holydocs migrate mintlify
```