cli

name

cli

description

@farming-labs/docs CLI — scaffold, upgrade, downgrade, deploy hosted Docs Cloud previews, run doctor audits, export static Agent Bundles, compact agent docs, validate code blocks, generate AGENTS.md, sitemaps, and robots.txt, sync search indexes, and run MCP. Use for init, deploy, upgrade, doctor, agent export, agent compact, codeblocks validate, agents generate, sitemap generate, robots generate, search sync, mcp, and their flags. Covers framework detection and package managers.

@farming-labs/docs — CLI

The @farming-labs/docs CLI scaffolds, upgrades, downgrades, audits agent and reader readiness, compacts page-level agent docs, exports static Agent Bundles, validates fenced code blocks, reviews docs PR changes, generates AGENTS.md, syncs external search indexes, generates robots.txt policy files, deploys hosted Docs Cloud previews, and can run the built-in MCP server for documentation projects. Use this skill when the user asks about CLI commands, init, upgrade, downgrade, doctor, agent export, agent compact, codeblocks validate, agents generate, sitemap generate, robots generate, search sync, mcp, review, preview, deploy, cloud preview, cloud deploy, cloud sync, or scaffolding.

---

Init (add docs or bootstrap project)

Run without flags: From the project root, run init. The CLI first asks: Are you adding docs to an existing project or starting fresh?

# npm
npx @farming-labs/docs@latest init

# pnpm
pnpm dlx @farming-labs/docs@latest init

# yarn
yarn dlx @farming-labs/docs@latest init

# bun
bunx @farming-labs/docs@latest init

• Existing project — Add docs to the current directory. CLI then detects framework (or prompts), asks for theme (including Create your own theme, which prompts for theme name and scaffolds themes/<name>.ts and themes/<name>.css), entry path (default docs), optional i18n scaffolding, path aliases, global CSS, and optional Docs Cloud infrastructure support. TanStack Start follows the same flow, but the CLI currently skips the built-in i18n scaffold there so the generated routes stay minimal and working. Prompts that show a placeholder use it as the default — press Enter to accept (e.g. entry path docs, theme name my-theme, project name my-docs).
• Fresh project — Bootstrap a new app. CLI asks for framework (Next.js, Nuxt, SvelteKit, Astro, TanStack Start), then project name (default my-docs; press Enter to accept), creates the folder, clones the template with degit, runs install using the package manager you chose, and can optionally add Docs Cloud infrastructure support. You then cd <name> and run the matching dev command for that package manager.

If you use --template with --name, the CLI skips the existing-vs-fresh prompt and goes straight to bootstrap (same as choosing Fresh and then framework + name).

Bootstrap without prompts (non-interactive):

npx @farming-labs/docs@latest init --template next --name my-docs
npx @farming-labs/docs@latest init --template tanstack-start --name my-docs
npx @farming-labs/docs@latest init --template nuxt --name my-docs
npx @farming-labs/docs@latest init --template sveltekit --name my-docs
npx @farming-labs/docs@latest init --template astro --name my-docs

Replace my-docs with the desired folder name. Same pattern with pnpm dlx, yarn dlx, or bunx.

---

Init flags

Flag	Description
--template <name>	Bootstrap a project: next, tanstack-start, nuxt, sveltekit, astro. Use with --name. Skips the existing-vs-fresh prompt.
--name <project>	Project folder name when using --template (e.g. my-docs). If omitted with --template, CLI prompts (default my-docs).
--theme <name>	Skip theme prompt. Values: e.g. fumadocs, greentree, pixel-border, darksharp, colorful, darkbold, shiny, ledger, concrete, command-grid, hardline.
--entry <path>	Skip entry path prompt. Default is docs.
--api-reference	Enable API reference scaffold during init.
--no-api-reference	Explicitly skip the API reference scaffold.
--api-route-root <path>	Override the detected API route root written to apiReference.routeRoot (e.g. api, internal-api).
--cloud	Add Docs Cloud infrastructure support during init without prompting.
--no-cloud	Skip the Docs Cloud infrastructure prompt during init.

Example (non-interactive bootstrap with theme):

npx @farming-labs/docs@latest init --template next --name my-docs --theme pixel-border

Example (existing project with API reference):

npx @farming-labs/docs@latest init --theme greentree --entry docs --api-reference --api-route-root internal-api

If Docs Cloud support is enabled during init, the CLI updates the docs config, writes the safe docs.json contract, and prints the next steps: sign in to https://docs-app.farming-labs.dev, create a project API key, and add it to .env.local or the shell:

DOCS_CLOUD_API_KEY=fl_key_...
NEXT_PUBLIC_DOCS_CLOUD_PROJECT_ID=docs_cloud_project_id

The raw key is never written to docs.config.ts or docs.json.

---

Upgrade

Upgrade all @farming-labs/* docs packages to the latest version. Run from the app/package directory that contains the framework package.json (for monorepos, for example apps/web). The CLI auto-detects the framework from that package.json and upgrades the correct packages.

For the package manager, the CLI checks the current directory and then walks up parent directories looking for lockfiles (pnpm-lock.yaml, yarn.lock, bun.lock, bun.lockb, package-lock.json) or package.json#packageManager. If no package manager signal is found, it prompts the user to choose instead of defaulting to npm.

# npm
npx @farming-labs/docs@latest upgrade

# pnpm
pnpm dlx @farming-labs/docs@latest upgrade

# yarn
yarn dlx @farming-labs/docs@latest upgrade

# bun
bunx @farming-labs/docs@latest upgrade

Framework	Packages upgraded
Next.js	@farming-labs/docs, @farming-labs/theme, @farming-labs/next
TanStack Start	@farming-labs/docs, @farming-labs/theme, @farming-labs/tanstack-start
Nuxt	@farming-labs/docs, @farming-labs/nuxt, @farming-labs/nuxt-theme
SvelteKit	@farming-labs/docs, @farming-labs/svelte, @farming-labs/svelte-theme
Astro	@farming-labs/docs, @farming-labs/astro, @farming-labs/astro-theme

---

Upgrade flags

Explicit framework (e.g. in a monorepo or when auto-detect fails):

npx @farming-labs/docs@latest upgrade --framework tanstack-start
# or
npx @farming-labs/docs@latest upgrade tanstack-start

Valid values: next, tanstack-start, nuxt, sveltekit, astro.

Version target:

npx @farming-labs/docs@latest upgrade              # latest stable (default)
npx @farming-labs/docs@latest upgrade --latest     # same
npx @farming-labs/docs@latest upgrade --beta       # beta versions
npx @farming-labs/docs@latest upgrade --version 0.1.104
npx @farming-labs/docs@latest upgrade --dry-run    # print the install command only
npx @farming-labs/docs@latest upgrade@beta         # shorthand for --beta
npx @farming-labs/docs@latest upgrade@latest       # shorthand for --latest

Use --version <version> when the user needs an exact release instead of an npm dist-tag. If someone uses pnpx @farming-labs/docs upgrade@beta, treat it as the supported shorthand for upgrading to the latest beta dist-tag.

Use --dry-run to resolve the framework, package manager, target packages, and install command without changing package.json or lockfiles. This is useful in monorepos before running the real upgrade from an app directory like apps/web.

Downgrade

Downgrade all @farming-labs/* docs packages to a lower version. Run from the app/package directory that contains the framework package.json. The CLI auto-detects the framework and package manager like upgrade.

Without --version, downgrade fetches published @farming-labs/docs versions and installs the highest version lower than the current installed version.

npx @farming-labs/docs@latest downgrade
pnpm dlx @farming-labs/docs@latest downgrade

Use --version <version> to choose an exact lower version:

npx @farming-labs/docs@latest downgrade --version 0.1.103

Preview the downgrade command without changing dependencies:

npx @farming-labs/docs@latest downgrade --version 0.1.103 --dry-run

If the requested version is equal to or newer than the current installed version, downgrade stops and tells the user to use upgrade --version <version> for newer versions.

---

MCP

Run the built-in docs MCP server over stdio from the current project:

# npm / pnpx
pnpx @farming-labs/docs mcp

# pnpm
pnpm exec docs mcp

By default the command reads docs.config.ts[x] from the project root and reuses the configured entry and contentDir.

Use a custom config path when the file lives elsewhere:

pnpm exec docs mcp --config src/lib/docs.config.ts

The built-in MCP surface currently includes:

• list_docs
• list_pages
• get_navigation
• search_docs
• read_page
• get_code_examples
• get_config_schema
• get_context

list_docs returns page summaries grouped by docs section. Call it with no arguments for the full section tree, or with section such as getting-started to narrow the result before read_page.

get_code_examples parses fenced code block metadata from raw markdown/MDX and returns structured examples for agents. Use metadata like

```ts title="docs.config.ts" framework="nextjs" packageManager="pnpm" runnable
```

get_config_schema returns structured docs.config.ts option metadata. Use option for an exact path such as mcp.tools.getConfigSchema, or query for keyword filtering.

get_context accepts query, optional framework, version, and locale, plus a tokenBudget from 256 to 32000 (default 4000). It returns deterministic section chunks with source anchors and conservative UTF-8 byte accounting. Pages without a framework/version/locale scope remain eligible as general docs, while conflicting metadata is excluded. Equal scores use source URL ordering. The complete assembled context, including source headers and separators, is limited to tokenBudget UTF-8 bytes; conservativeTokenUpperBound reports that dependency-free upper bound. Successful built-in tools also return validated MCP structuredContent while preserving text output for compatibility.

when a snippet has a target file, framework, package manager, or is safe to copy as a complete example. This metadata is for markdown/MCP consumers and does not require a UI change.

Use the docs config mcp block when you also want the HTTP route version at /mcp or /.well-known/mcp.

Docs Cloud deploy

Use docs deploy from a docs project root to sync the serializable cloud block from docs.config.ts into docs.json, validate the configured API key, and deploy hosted preview docs.

pnpm dlx @farming-labs/docs deploy
pnpm dlx @farming-labs/docs preview
pnpm dlx @farming-labs/docs cloud deploy
pnpm dlx @farming-labs/docs cloud preview
pnpm dlx @farming-labs/docs cloud sync

Config shape:

cloud: {
  apiKey: { env: "DOCS_CLOUD_API_KEY" },
  deploy: { enabled: true },
  publish: { mode: "draft-pr", baseBranch: "main" },
}

• docs cloud sync only writes or updates docs.json.
• docs deploy auto-creates docs.json if the project has not run a cloud command before.
• docs preview and docs cloud preview remain compatibility aliases for hosted preview deployment.
• The API key value must live in the named env var, .env.local, or CI secrets. Never write the raw key into config.
• Use --config <path> when docs.config.ts lives outside the project root.
• Use --api-base-url <url> for staging/self-hosted cloud API testing.

Code block validation

Use docs codeblocks validate to scan MD/MDX fences, build execution plans from code fence metadata, and run executable snippets when codeBlocks.validate is enabled in docs.config.ts. Supported runners are local, vercel-sandbox, e2b, daytona, and the reserved cloud runner. E2B requires e2b; Daytona requires @daytona/sdk.

pnpm exec docs codeblocks validate --plan
pnpm exec docs codeblocks validate
pnpm exec docs codeblocks validate --json

Config example:

codeBlocks: {
  validate: {
    planner: {
      provider: "openai",
      model: "gpt-4.1-mini",
      apiKeyEnv: "OPENAI_API_KEY",
    },
    runner: {
      provider: "vercel-sandbox",
      tokenEnv: "VERCEL_TOKEN",
    },
    envFile: [".env.local", ".env.test", ".env"],
    env: {
      OPENAI_API_KEY: "OPENAI_TEST_API_KEY",
    },
  },
}

Fence metadata example:

```ts title="app/api/chat/route.ts" framework="nextjs" packageManager="pnpm" env="OPENAI_API_KEY" runnable
const apiKey = process.env.OPENAI_API_KEY;
```

The env map injects runtime env names from local test env vars. Do not put actual secrets in docs.config.ts.

Docs Review

Use docs review to score changed docs files, check broken internal links, required frontmatter, code fence metadata, runnable snippet metadata, and agent-context suggestions.

pnpm exec docs review
pnpm exec docs review --ci
pnpm exec docs review setup

withDocs() creates .github/workflows/docs-review.yml automatically during next dev or next build when review CI is enabled and the workflow does not already exist. The generated file is a tiny wrapper around farming-labs/docs/.github/workflows/docs-review-reusable.yml@main. Omitted review config is enabled by default; use review: false to opt out.

Use review.ci.mode: "block" and review.score.threshold when the team wants CI to fail below a score threshold. Use review.ci.name to customize the GitHub Actions job/check name; it defaults to docs-review.

Search Sync

Use search sync when you want to push docs content into Typesense or Algolia from the CLI instead of waiting for the first search request to trigger indexing.

pnpm dlx @farming-labs/docs search sync --typesense

pnpm dlx @farming-labs/docs search sync --algolia

The command:

• reads .env / .env.local from the current project
• scans docs content using entry / contentDir from docs.config
• uploads normalized search documents to the selected backend
• also supports the generic form pnpm dlx @farming-labs/docs search sync --provider typesense or --provider algolia

Typesense env:

TYPESENSE_URL=https://your-cluster.a1.typesense.net
TYPESENSE_API_KEY=your-admin-capable-key

Optional:

TYPESENSE_COLLECTION=docs
TYPESENSE_MODE=hybrid
TYPESENSE_OLLAMA_MODEL=embeddinggemma
TYPESENSE_OLLAMA_BASE_URL=http://127.0.0.1:11434

Algolia env:

ALGOLIA_APP_ID=your-app-id
ALGOLIA_ADMIN_API_KEY=your-admin-key
ALGOLIA_SEARCH_API_KEY=your-search-key

For a working repo example, the Next example can switch between MCP, Typesense, and Algolia:

pnpm --dir examples/next dev

Useful checks:

pnpm --dir examples/next exec docs search sync --typesense --config docs.config.tsx
pnpm --dir examples/next exec docs search sync --algolia --config docs.config.tsx

Then verify:

• MCP: http://127.0.0.1:3000/mcp or http://127.0.0.1:3000/.well-known/mcp
• Search: http://127.0.0.1:3000/api/docs?query=session

---

Sitemap generate

Use sitemap generate when the user wants static sitemap files, lastmod freshness metadata, or CI validation for generated sitemap output.

pnpm exec docs sitemap generate
pnpm exec docs sitemap generate --config src/lib/docs.config.ts
pnpm exec docs sitemap generate --manifest-only
pnpm exec docs sitemap generate --check

Behavior:

• reads docs.config.ts[x] by default, or the path passed with --config
• scans docs content using entry and contentDir
• writes .farming-labs/sitemap-manifest.json
• writes public sitemap files by default: sitemap.xml, sitemap.md, docs/sitemap.md, and .well-known/sitemap.md
• writes to static/ for SvelteKit and public/ for other frameworks
• resolves lastmod from git log -1 for each page source path, falling back to filesystem mtime
• preserves generatedAt when the comparable manifest content has not changed

Flags:

Flag	Description
--config <path>	Use a custom docs config path.
--manifest-only	Only write .farming-labs/sitemap-manifest.json.
--public	Explicitly write public sitemap files; this is already the default unless --manifest-only is set.
--check	Fail when generated output is stale.

Build script examples:

{
  "scripts": {
    "build": "docs sitemap generate --config src/lib/docs.config.ts && astro build"
  }
}

{
  "scripts": {
    "build": "docs sitemap generate --manifest-only && next build"
  }
}

For normal published apps, package scripts can call docs because the installed package exposes the bin. In this repo while dogfooding unpublished workspace builds, call the built CLI file directly after @farming-labs/docs has been built if the package bin is not available.

Use the configuration skill or /docs/customization/sitemaps for sitemap config options and output examples.

---

Agent export

Use agent export when static hosting needs the full agent-facing route surface without a server handler.

pnpm exec docs agent export --public
pnpm exec docs agent export --check
pnpm exec docs agent export --public --config src/lib/docs.config.ts

Behavior:

• --public is required for writes and targets public/, or static/ for SvelteKit
• --check performs the same resolution without writing and fails when any output is stale
• exports every resolved page as .md, honoring agent.md, then Agent blocks, then page content
• exports root/entry/well-known/configured-section llms.txt files, discovery JSON, skill and AGENTS aliases, sitemaps, and robots.txt
• writes /.well-known/agent-bundle.json and .farming-labs/agent-bundle-manifest.json with deterministic SHA-256 hashes
• treats the exported artifact as static even when staticExport is omitted: discovery disables server-only search, MCP, feedback, API reference, and OpenAPI capabilities
• uses tracked git commit dates for exported page freshness and omits checkout-specific filesystem mtimes, so --check is reproducible across clean clones
• preserves native page, llms.txt, discovery, skill, public AGENTS.md, and robots.txt overrides
• never copies repository-root AGENTS.md; use docs agents generate when publishing those instructions is intentional
• writes files through same-directory temporary files and atomic renames
• removes obsolete outputs only when their contents still match the prior managed manifest hash; edited obsolete files remain marked as orphaned and keep --check failing until removed manually
• rejects public and internal output paths that escape their declared roots through symlinks

Use it before a static framework build:

{
  "scripts": {
    "build": "docs agent export --public && next build",
    "check:agents": "docs agent export --check"
  }
}

---

Agent compact

Use agent compact when the user wants generated agent.md files, shorter page-level machine docs, or a tighter machine-readable version of existing docs pages.

pnpm exec docs agent compact installation configuration
pnpm exec docs agent compact /docs/installation
pnpm exec docs agent compact /docs/installation.md
pnpm exec docs agent compact https://docs.example.com/docs/installation
pnpm exec docs agent compact . --dry-run
pnpm exec docs agent compact --page installation --page configuration
pnpm exec docs agent compact --all
pnpm exec docs agent compact --changed
pnpm exec docs agent compact --stale
pnpm exec docs agent compact --stale --include-missing

Behavior:

• positional page args are the preferred UX; --page is an optional repeatable alias
• page identifiers can be a slug, docs path, .md path, full docs URL, or . for the root docs page
• the command loads .env and .env.local
• the Docs Cloud API key comes from root cloud.apiKey.env; --api-key and --api-key-env are one-off overrides
• compression defaults can come from agent.compact in docs.config.ts or docs.config.tsx
• --changed compacts only docs pages changed in the current git working tree, including staged, unstaged, and untracked docs changes plus handwritten agent.md sources
• --stale refreshes only generated agent.md files whose page source or compaction settings changed
• --include-missing only works with --stale, and creates missing agent.md files for explicit pages or pages that define agent.tokenBudget
• it creates missing sibling agent.md files and overwrites existing ones
• the written agent.md becomes the machine-readable source for .md routes, GET /api/docs?format=markdown&path=..., and MCP read_page()
• only folder-based pages can be written automatically
• page frontmatter agent.tokenBudget overrides the compact output target for that one page
• if the page budget is lower than inherited minOutputTokens, the CLI clamps the minimum down to the page budget before calling the compression API
• generated files carry hidden provenance metadata so docs doctor --agent can report fresh, stale, modified, unknown, and token-budget-missing compaction states

Recommended config:

cloud: {
  apiKey: { env: "DOCS_CLOUD_API_KEY" },
},
agent: {
  compact: {
    model: "docs-cloud-compress-v1",
    aggressiveness: 0.3,
    protectJson: true,
  },
}

Useful checks:

pnpm exec docs agent compact installation --dry-run
pnpm exec docs agent compact installation
curl "http://127.0.0.1:3000/docs/installation.md"

Per-page override example:

---
title: "Installation"
agent:
  tokenBudget: 777
---

---

Agents generate

Use agents generate when the user wants root and static AGENTS.md files for coding agents. Server-rendered apps get generated /AGENTS.md dynamically by default, but static exports can commit the generated files.

pnpm exec docs agents generate
pnpm exec docs agents generate --check
pnpm exec docs agents generate --force
pnpm exec docs agents generate --path AGENTS.md

Behavior:

• writes a managed root AGENTS.md
• writes public aliases at /AGENTS.md, /.well-known/AGENTS.md, /AGENT.md, and /.well-known/AGENT.md
• uses public/ by default, or static/ for SvelteKit
• keeps a hand-written root AGENTS.md or AGENT.md unless --force is passed
• copies a hand-written root file to missing public aliases for static hosting

---

Robots generate

Use robots generate when the user wants a static robots.txt policy that advertises docs routes, agent-readable markdown routes, llms.txt, sitemap routes, AGENTS.md, skill.md, MCP aliases, and common AI crawler user agents.

pnpm exec docs robots generate
pnpm exec docs robots generate --append
pnpm exec docs robots generate --force
pnpm exec docs robots generate --path public/robots.txt --append
pnpm exec docs robots generate --check
pnpm exec docs robots generate --config src/lib/docs.config.ts

Behavior:

• default output is public/robots.txt, or static/robots.txt for SvelteKit
• robots.path in docs.config.ts sets the default path
• positional path or --path overrides the configured/default path
• existing unknown files are preserved by default
• --append adds or updates the generated managed block inside an existing file
• --force replaces the whole file with the generated policy
• --check fails when the resolved file is stale

Use docs doctor --agent after generation; it checks the resolved robots path and warns when agent routes or common AI crawlers are blocked.

---

Doctor

Use docs doctor --agent when the user wants to inspect, score, or validate the machine-facing docs surface instead of generating content.

Use docs doctor --site when the user wants the same kind of audit for the reader-facing docs experience instead.

pnpm exec docs doctor
pnpm exec docs doctor --agent
pnpm exec docs doctor --site
pnpm exec docs doctor --agent --json
pnpm exec docs doctor agent
pnpm exec docs doctor site
pnpm exec docs doctor --agent --config docs.config.tsx
pnpm exec docs doctor --agent --url https://docs.example.com
pnpm exec docs doctor --agent --url https://docs.example.com --json

What it checks:

• docs config
• docs content
• framework docs API route
• public agent routes
• agent discovery spec
• llms.txt
• sitemap.xml, sitemap.md, and docs/sitemap.md
• robots.txt
• AGENTS.md
• skill.md
• MCP
• search
• agent feedback, which is enabled by default and can be explicitly opted out
• page metadata
• explicit agent-friendly pages
• generated agent.md freshness and agent.compact defaults

With --url, docs doctor --agent also probes the deployed public agent surface:

• /.well-known/agent.json
• /llms.txt
• /llms-full.txt
• sitemap routes from the discovery spec, usually /sitemap.xml, /sitemap.md, /docs/sitemap.md, and /.well-known/sitemap.md
• the robots route from the discovery spec, usually /robots.txt
• /AGENTS.md
• /.well-known/AGENTS.md
• /skill.md
• /.well-known/skill.md
• one representative .md page route, such as /docs.md
• /mcp
• /.well-known/mcp
• https://mcp.<your-domain>/mcp
• https://mcp.<your-domain>/

For hosted MCP, the command performs a Streamable HTTP initialize handshake, checks for mcp-session-id, calls tools/list, and expects list_docs, list_pages, get_navigation, search_docs, read_page, get_code_examples, get_config_schema, and get_context. Hosted checks raise the agent max score from 105 to 145.

Hosted JSON check IDs include hosted-agent-discovery, hosted-llms, hosted-sitemap, hosted-robots, hosted-skill, hosted-markdown, and hosted-mcp.

Expected shape of the output:

@farming-labs/docs doctor — agent

Score: 92/105 (Agent-ready)
Framework: nextjs • Entry: docs • Content: app/docs
Explicit agent-friendly pages: 10/41 pages (24%)

PASS Docs API route (10/10)
WARN Skill document (3/5)
WARN Explicit page optimization (5/10)

How to explain it:

• the command is a health check, not a generator
• it is not required for the framework to run
• it becomes important when the user wants to claim the docs are agent-ready, agent-optimized, or GEO-friendly
• low Explicit agent-friendly pages does not mean pages are invisible to agents; it means fewer pages have extra machine-only context through agent.md or Agent blocks
• --json is for CI, scripts, dashboards, and other agents that need structured output instead of terminal formatting
• --url is for deployed or preview sites; use it after local static checks pass and you want to confirm public rewrites, .well-known routes, markdown routes, and MCP are reachable
• the JSON report itself is written to stdout; separate loader notices, such as config fallback warnings, are outside the JSON payload

Useful checks:

pnpm --dir examples/next exec docs doctor --agent --config docs.config.tsx
pnpm --dir examples/next exec docs doctor --agent --config docs.config.tsx --url http://127.0.0.1:3000
pnpm --dir examples/next exec docs doctor --site --config docs.config.tsx
pnpm --dir website exec docs doctor --agent --config docs.config.tsx

---

What init does (Existing project, per framework)

When the user chooses Existing project, the CLI detects (or prompts for) framework, then theme (including Create your own theme → prompts for theme name, scaffolds themes/<name>.ts and themes/<name>.css), path aliases, entry path (default docs; Enter to accept), optional API reference scaffold, optional i18n scaffolding, and global CSS. If API reference is enabled and the user does not pass --api-route-root, the CLI detects a sensible default route root (usually api) and shows it as the default in the prompt. Generated files:

• Next.js: docs.config.ts, next.config.ts, app/global.css, app/layout.tsx, app/docs/layout.tsx, sample MDX pages; installs @farming-labs/docs, @farming-labs/theme, @farming-labs/next; can start dev server. If API reference is enabled, the CLI writes the default Fumadocs page at app/api-reference/[[...slug]]/page.tsx (or src/app/...); renderer: "scalar" uses the generated Scalar route handler.
• TanStack Start: docs.config.ts, src/lib/docs.server.ts, src/lib/docs.functions.ts, src/routes/<entry>/index.tsx, src/routes/<entry>/$.tsx, src/routes/api/docs.ts, one src/routes/$.ts public docs forwarder for /llms.txt, sitemap routes, .well-known, .md, and MCP, optional src/routes/api-reference.index.ts + src/routes/api-reference.$.ts, updates src/routes/__root.tsx, updates vite.config.ts, and wires theme CSS into the selected global stylesheet; installs @farming-labs/docs, @farming-labs/theme, @farming-labs/tanstack-start.
• SvelteKit: src/lib/docs.config.ts, src/lib/docs.server.ts, src/routes/docs/*, src/routes/api/docs/+server.ts, one src/hooks.server.ts public docs forwarder for /llms.txt, sitemap routes, .well-known, .md, and MCP, optional src/routes/api-reference/+server.ts + src/routes/api-reference/[...slug]/+server.ts, src/app.css, docs/*.md; installs svelte + svelte-theme packages.
• Astro: src/lib/docs.config.ts, src/lib/docs.server.ts, src/pages/**, src/pages/api/docs.ts, one src/middleware.ts public docs forwarder for /llms.txt, sitemap routes, .well-known, .md, and MCP, optional src/pages/api-reference/index.ts + src/pages/api-reference/[...slug].ts, docs/*.md; installs astro + astro-theme packages.
• Nuxt: docs.config.ts, nuxt.config.ts, server/api/docs.ts, server/middleware/docs-public.ts for /llms.txt, sitemap routes, .well-known, .md, and MCP forwarding, optional server/routes/api-reference/index.ts + server/routes/api-reference/[...slug].ts, pages/docs/[...slug].vue, docs/*.md; installs nuxt + nuxt-theme packages.

Create your own theme: If the user selects this, the CLI prompts for a theme name (default my-theme; Enter to accept), then creates themes/<name>.ts and themes/<name>.css and wires them in docs.config and global CSS. See the creating-themes skill for the API.

Optional i18n scaffold: On existing projects, the CLI can scaffold query-param locale support. It asks whether to enable i18n, lets the user multi-select common languages like en, fr, es, de, pt, ja, ko, zh, ar, hi, and ru, accepts extra locale codes like pt-BR, and then asks for the default locale. It writes the i18n block to docs.config, generates locale folders such as docs/en and docs/fr, and scaffolds the extra wrapper/root files needed by each framework.

---

Edge cases

1. Monorepo — Run init from the app package root (where package.json with the framework dependency lives). For upgrade, use --framework if auto-detect picks the wrong one.
2. No package.json / wrong directory — Init and upgrade must run in a directory that has (or will have) a package.json with the framework dependency.
3. Beta — Use upgrade --beta to get beta versions of the docs packages.
4. TanStack Start local package development — In this repo's examples and other monorepos, prefer local links such as workspace:* for @farming-labs/docs, @farming-labs/theme, and @farming-labs/tanstack-start while testing unpublished changes. On Node 22 / Vercel, this prevents the adapter Vite entry from resolving to raw TypeScript inside node_modules.

---

Resources

• Full CLI docs: docs.farming-labs.dev/docs/cli
• Token efficiency: docs.farming-labs.dev/docs/token-efficiency
• Getting started: use the getting-started skill in this repo for install and theme CSS.