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

# holydocs deploy

Trigger a HolyDocs deployment from the command line.

## Usage

```bash
holydocs deploy [options]
```

Triggers a deployment for your HolyDocs project. The CLI asks the API to build the connected repository and, by default, waits while the deployment moves through queued, building, and success or failed states.

## Options

| Option | Description | Default |
|---|---|---|
| `--project <id>` | Project ID to deploy | From `HOLYDOCS_PROJECT` or local config |
| `--branch <name>` | Branch to deploy | Server default / connected branch |
| `--no-watch` | Queue the deployment and exit immediately | Watches deployment progress |

## Examples

### Deploy Using Your Default Project

```bash
holydocs deploy
```

Output:

```
  Triggering deployment...
✓ Deployment queued (dep_xyz78)
✓ Deployed in 8.1s
  Commit: c7f3e2a — Update authentication guide
```

### Deploy a Specific Project

```bash
holydocs deploy --project proj_abc123
```

### Deploy a Specific Branch

```bash
holydocs deploy --branch release-docs
```

### Queue and Exit

```bash
holydocs deploy --no-watch
```

The CLI prints the deployment ID and exits so another system can track the result.

## Authentication

`deploy` requires API authentication. You can either:

1. Run [`holydocs login`](/cli/login) once and reuse the saved config
2. Set `HOLYDOCS_API_KEY` and `HOLYDOCS_PROJECT` in the environment

```bash
HOLYDOCS_API_KEY=hd_a1b2c3d4e5f67890a1b2c3d4e5f67890 \
HOLYDOCS_PROJECT=proj_abc123 \
holydocs deploy --no-watch
```

## Project Resolution

The project ID is resolved in this order:

1. `--project`
2. `HOLYDOCS_PROJECT`
3. `projectId` in `~/.holydocs/config.json`

If none of those exist, the command exits with an error.

## Local Files vs Remote Repository

`holydocs deploy` triggers a build for the project connected in HolyDocs. It does not upload your local files directly.

If the CLI cannot find a local `docs.json`, it prints a warning and still triggers the remote deployment. This is useful in CI or from machines that are not inside the docs repo.

## CI Example

```yaml
# GitHub Actions
- name: Deploy docs
  run: npx @holydocs/cli deploy --no-watch
  env:
    HOLYDOCS_API_KEY: ${{ secrets.HOLYDOCS_API_KEY }}
    HOLYDOCS_PROJECT: ${{ secrets.HOLYDOCS_PROJECT_ID }}
```

Pair `holydocs deploy` with [`holydocs status`](/cli/status) when you want to inspect a failed deployment after the fact.