DeployCopy Anchor Link

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.

RequirementsCopy Anchor Link

• 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

Configure CloudCopy Anchor Link

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.jsonCopy Anchor Link

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.

pnpm dlx @farming-labs/docs cloud sync

Example output:

{
  "$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 PreviewCopy Anchor Link

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

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:

pnpm dlx @farming-labs/docs cloud deploy

Check Cloud SetupCopy Anchor Link

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

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:

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

--ask-ai checks the Docs Cloud provider path end to end. Direct browser mode needs PUBLIC_DOCS_CLOUD_PROJECT_ID plus PUBLIC_DOCS_CLOUD_API_KEY or another browser-safe cloud.apiKey.env; Next.js projects can use the equivalent NEXT_PUBLIC_* names. The check also sends a browser-style CORS preflight to the hosted knowledge endpoint. If only the server-side project id and API key are available, the report marks the local docs API route as the proxy path and skips browser CORS for Ask AI because the browser only talks to the same-origin docs app.

Example focused report:

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 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:

pnpm dlx @farming-labs/docs deploy --json

CommandsCopy Anchor Link

--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 ModeCopy Anchor Link

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

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

TroubleshootingCopy Anchor Link

Missing API keyCopy Anchor Link

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

export DOCS_CLOUD_API_KEY=fl_key_...

or add it to .env.local.

Deploy disabledCopy Anchor Link

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 blockedCopy Anchor Link

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 hostCopy Anchor Link

For staging or self-hosted testing, pass:

pnpm dlx @farming-labs/docs deploy --api-base-url https://cloud.example.com