---
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"
agent:
  tokenBudget: 1000
  task: "Configure a repository and deploy a hosted Docs Cloud preview."
  outcome: "Docs Cloud accepts the synchronized contract and returns a preview deployment URL."
  appliesTo:
    framework:
      - "nextjs"
      - "tanstackstart"
      - "sveltekit"
      - "astro"
      - "nuxt"
    version:
      - ">=0.2.60"
    package:
      - "@farming-labs/docs"
  prerequisites:
    - "The workspace has Docs Cloud access and a connected project."
    - "DOCS_CLOUD_API_KEY is available through the shell, .env.local, or CI secrets."
    - "The cloud deploy setting is enabled in docs.config."
  files:
    - "docs.config.ts"
    - "docs.config.tsx"
    - "src/lib/docs.config.ts"
    - "docs.json"
    - ".env.local"
  commands:
    - run: "pnpm dlx @farming-labs/docs cloud sync"
      description: "Synchronize safe Cloud settings into docs.json."
    - run: "pnpm dlx @farming-labs/docs cloud check --deploy --no-network"
      description: "Validate the local deployment contract before making a hosted request."
    - run: "pnpm dlx @farming-labs/docs deploy --json"
      description: "Create or update the hosted preview and return machine-readable output."
  sideEffects:
    - "cloud sync writes or updates docs.json."
    - "deploy creates or updates a hosted Docs Cloud preview."
  verification:
    - run: "pnpm dlx @farming-labs/docs cloud check --deploy"
      expect: "Config, docs.json freshness, API key, deploy scopes, and hosted API checks pass."
    - description: "Confirm the JSON deploy response includes the expected project and preview URL."
  rollback:
    - "Restore the previous docs.json and docs.config cloud block from version control."
    - "Disable cloud.deploy and remove the unwanted preview from the Docs Cloud project."
  failureModes:
    - symptom: "The CLI reports a missing or invalid API key."
      resolution: "Set the environment variable named by cloud.apiKey.env and never put the raw value in committed config."
    - symptom: "Browser checks report a CORS failure."
      resolution: "Configure the public docs origin and allow that exact origin in a self-hosted Cloud API."
---

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Configure a repository and deploy a hosted Docs Cloud preview.
Outcome: Docs Cloud accepts the synchronized contract and returns a preview deployment URL.

### Applies To

- Framework: `nextjs`, `tanstackstart`, `sveltekit`, `astro`, `nuxt`
- Version: `>=0.2.60`
- Package: `@farming-labs/docs`

### Prerequisites

- The workspace has Docs Cloud access and a connected project.
- DOCS_CLOUD_API_KEY is available through the shell, .env.local, or CI secrets.
- The cloud deploy setting is enabled in docs.config.

### Files

- `docs.config.ts`
- `docs.config.tsx`
- `src/lib/docs.config.ts`
- `docs.json`
- `.env.local`

### Commands

- `pnpm dlx @farming-labs/docs cloud sync` — Synchronize safe Cloud settings into docs.json.
- `pnpm dlx @farming-labs/docs cloud check --deploy --no-network` — Validate the local deployment contract before making a hosted request.
- `pnpm dlx @farming-labs/docs deploy --json` — Create or update the hosted preview and return machine-readable output.

### Side Effects

- cloud sync writes or updates docs.json.
- deploy creates or updates a hosted Docs Cloud preview.

### Verification

- Run `pnpm dlx @farming-labs/docs cloud check --deploy`
  - Expected: Config, docs.json freshness, API key, deploy scopes, and hosted API checks pass.
- Confirm the JSON deploy response includes the expected project and preview URL.

### Rollback

- Restore the previous docs.json and docs.config cloud block from version control.
- Disable cloud.deploy and remove the unwanted preview from the Docs Cloud project.

### Failure Modes

- The CLI reports a missing or invalid API key. — Recovery: Set the environment variable named by cloud.apiKey.env and never put the raw value in committed config.
- Browser checks report a CORS failure. — Recovery: Configure the public docs origin and allow that exact origin in a self-hosted Cloud API.
<!-- farming-labs:agent-contract:end -->

# Deploy

## Deploy task

Task: Configure a repository and deploy a hosted Docs Cloud preview.

Expected result: Docs Cloud accepts the synchronized contract and returns a preview deployment URL.

Exact implementation:

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

- The workspace has Docs Cloud access and a connected project.
- DOCS_CLOUD_API_KEY is available through the shell, .env.local, or CI secrets.
- The cloud deploy setting is enabled in docs.config.
- Applies to framework nextjs, tanstackstart, sveltekit, astro, nuxt; version >=0.2.60; package @farming-labs/docs.

## Deploy verification

- Run pnpm dlx @farming-labs/docs cloud check --deploy. Expected: Config, docs.json freshness, API key, deploy scopes, and hosted API checks pass.
- Confirm the JSON deploy response includes the expected project and preview URL.
- Failure: The CLI reports a missing or invalid API key.
- Recovery: Set the environment variable named by cloud.apiKey.env and never put the raw value in committed config.
- Rollback: Restore the previous docs.json and docs.config cloud block from version control.

## Deploy agent guidance

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.

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