---
title: "Deploy"
description: "Deploy a Docs Cloud preview from docs.config.ts, docs.json, and a project API key"
canonical_url: "https://docs.farming-labs.dev/docs/cloud/deploy"
markdown_url: "https://docs.farming-labs.dev/docs/cloud/deploy.md"
last_updated: "2018-10-20"
---

# Deploy
URL: /docs/cloud/deploy
LLM index: /llms.txt
Description: Deploy a Docs Cloud preview from docs.config.ts, docs.json, and a project API key
Related: /docs/cloud, /docs/cloud/analytics, /docs/guides/docs-json, /docs/cli

# Deploy

Use this page when the user asks about this topic: Docs Cloud deploys, hosted preview docs, Docs Cloud API keys, docs.config.ts cloud config, docs.json sync, publish modes, and deploy troubleshooting.
Keep answers technical and grounded in the commands and config on this page. Never suggest committing raw API key values to docs.config.ts, docs.json, or source control.
If the request is about hosted analytics, project identity, or event storage, point to /docs/cloud/analytics. If the request is about the docs.json contract itself, point to /docs/guides/docs-json.

Docs Cloud deploy creates a hosted preview for a connected docs project. The repo remains the source
of truth. The CLI syncs the serializable Cloud config into `docs.json`, validates the project API
key, then asks Docs Cloud to create or update the preview.

## Requirements

- Docs Cloud access for the workspace
- a Docs Cloud project API key
- `DOCS_CLOUD_API_KEY` available in your shell, `.env.local`, or CI secrets
- a `cloud` block in `docs.config.ts`
- a committed `docs.json` when the repo contract should be reviewed in Git

<Callout type="caution" title="Do not commit secrets">
  Keep the raw API key in `.env.local`, your shell, or CI secrets. `docs.config.ts` should reference
  the environment variable name, and `docs.json` should only contain that environment variable name.
</Callout>

## Configure Cloud

```ts title="docs.config.ts"
import { defineDocs } from "@farming-labs/docs";

export default defineDocs({
  entry: "docs",
  cloud: {
    apiKey: { env: "DOCS_CLOUD_API_KEY" },
    deploy: { enabled: true },
    publish: { mode: "draft-pr", baseBranch: "main" },
  },
});
```

`cloud.apiKey.env` defaults to `DOCS_CLOUD_API_KEY`. Writing it explicitly makes the contract easier
to review in CI and pull requests.

## Sync `docs.json`

`docs.json` is the JSON contract that Docs Cloud reads. It mirrors safe Cloud settings from
`docs.config.ts`; it does not store API key values.

```bash title="terminal"
pnpm dlx @farming-labs/docs cloud sync
```

Example output:

```json title="docs.json"
{
  "$schema": "https://docs.farming-labs.dev/schema/docs.json",
  "version": 1,
  "docs": {
    "mode": "framework",
    "runtime": "nextjs",
    "root": "."
  },
  "content": {
    "docsRoot": "docs"
  },
  "cloud": {
    "apiKey": {
      "env": "DOCS_CLOUD_API_KEY"
    },
    "deploy": {
      "enabled": true
    },
    "publish": {
      "mode": "draft-pr",
      "baseBranch": "main"
    }
  }
}
```

The generated `cloud` block intentionally omits `enabled`. The presence of the block opts the
project into Cloud-aware CLI flows. Set `"enabled": false` only when the repo should keep the local
contract but disable Cloud operations.

## Deploy A Preview

Set the key, then run the deploy command from the project root:

```bash title="terminal"
export DOCS_CLOUD_API_KEY=fl_key_...
pnpm dlx @farming-labs/docs deploy
```

`docs deploy` performs the same sync step before requesting the preview:

1. read `docs.config.ts`
2. write or update `docs.json`
3. validate the Docs Cloud API key
4. request a hosted preview deployment

The explicit Cloud command is equivalent:

```bash title="terminal"
pnpm dlx @farming-labs/docs cloud deploy
```

## Check Cloud Setup

Run a read-only health check before deploying or debugging Ask AI:

```bash title="terminal"
pnpm dlx @farming-labs/docs cloud check
```

The check validates `docs.config.ts`, `docs.json` freshness, the hosted Docs Cloud API target,
`cloud.apiKey.env`, the Docs Cloud API key, required deploy scopes, analytics project envs,
the public docs origin used for browser CORS, `ai.provider: "docs-cloud"` direct or proxied
knowledge endpoint wiring, and browser CORS preflight for Cloud analytics/Ask AI. Use `--json` in CI or
`--no-network` when you only want local config checks.

Scope the report when you only want one integration area:

```bash title="terminal"
pnpm dlx @farming-labs/docs cloud check --analytics
pnpm dlx @farming-labs/docs cloud check --ask-ai
pnpm dlx @farming-labs/docs cloud check --deploy
```

Example focused report:

```txt title="terminal"
Docs Cloud check
api https://api.farming-labs.dev
scope analytics

ok config Loaded docs.config.ts
warn docs.json docs.json is missing. Run docs cloud sync to materialize cloud config.
ok cloud.apiBaseUrl Using the hosted Docs Cloud API at https://api.farming-labs.dev.
ok docs.siteOrigin Public docs origin is https://docs.example.com.
ok cloud.enabled Docs Cloud is enabled.
ok analytics.runtime Runtime analytics is not disabled.
ok analytics.cloud Docs Cloud analytics is enabled in cloud.analytics.
ok project.env Docs Cloud project id is present in NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID.
ok cors.analytics Analytics CORS allows https://docs.example.com.

ok Docs Cloud check passed with 1 warning.
```

Use JSON output when CI or another tool needs the preview URL:

```bash title="terminal"
pnpm dlx @farming-labs/docs deploy --json
```

## Commands

| Command | Use it when |
| ------- | ----------- |
| `pnpm dlx @farming-labs/docs cloud sync` | You only want to update `docs.json` |
| `pnpm dlx @farming-labs/docs cloud check` | You want to validate config, hosted API access, analytics envs, API key scopes, CORS, and Ask AI wiring without deploying |
| `pnpm dlx @farming-labs/docs cloud check --analytics` | You only want to validate Docs Cloud analytics wiring and analytics CORS |
| `pnpm dlx @farming-labs/docs cloud check --ask-ai` | You only want to validate Docs Cloud Ask AI endpoint wiring and Ask AI CORS |
| `pnpm dlx @farming-labs/docs cloud check --deploy` | You only want to validate deploy flags, API key presence, and deploy scopes |
| `pnpm dlx @farming-labs/docs deploy` | You want to sync, validate the key, and request a preview |
| `pnpm dlx @farming-labs/docs cloud deploy` | You prefer the explicit Cloud namespace |
| `pnpm dlx @farming-labs/docs deploy --json` | CI needs machine-readable output |
| `pnpm dlx @farming-labs/docs deploy --config <path>` | The docs config file is outside the project root |
| `pnpm dlx @farming-labs/docs deploy --api-base-url <url>` | You are testing a staging or self-hosted Cloud API |

`--api-key <key>` is available for local testing. Prefer `cloud.apiKey.env` plus an environment
variable for normal use so the key does not end up in shell history or logs.

## Publish Mode

`cloud.publish` controls what Docs Cloud should do when generated docs changes need to go back to
Git:

| Mode | Behavior |
| ---- | -------- |
| `"draft-pr"` | Create a draft pull request targeting `publish.baseBranch` |
| `"direct-commit"` | Commit directly to `publish.baseBranch` |

Use `draft-pr` for normal team workflows. Reserve `direct-commit` for trusted automation where the
Cloud project owns the branch policy.

## Troubleshooting

### Missing API key

Set the environment variable named by `cloud.apiKey.env`:

```bash title="terminal"
export DOCS_CLOUD_API_KEY=fl_key_...
```

or add it to `.env.local`.

### Deploy disabled

If `cloud.deploy.enabled` is `false`, `docs deploy` stops before requesting a hosted preview. Set it
back to `true` or remove the override.

### Browser CORS blocked

Make sure the public docs URL is set in one of the places the check can read:
`NEXT_PUBLIC_BASE_URL`, `NEXT_PUBLIC_SITE_URL`, `SITE_URL`, `site.url`, `sitemap.baseUrl`,
`llmsTxt.baseUrl`, or `robots.baseUrl`.

For the hosted Docs Cloud API, you do not need to set a Docs Cloud API URL. If you are
self-hosting the API, allow the same public docs origin in the API service CORS config.

### Wrong Cloud host

For staging or self-hosted testing, pass:

```bash title="terminal"
pnpm dlx @farming-labs/docs deploy --api-base-url https://cloud.example.com
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).