CLI Commands & Tooling

Overview

The DeepDoc CLI (deepdoc/cli.py) is the primary interface for generating, updating, previewing, and deploying documentation for code repositories. It orchestrates the entire documentation lifecycle, from initializing configuration to building and serving a Fumadocs-powered site, and integrates with LLM providers (Anthropic, OpenAI, Ollama, Azure) and optional chatbot/embedding backends.

The CLI is designed for developer productivity, enabling both one-off and automated workflows. It is deeply integrated with the Pipeline & Generation Engine, Site Generation & Frontend Integration Overview, and supports advanced features like smart incremental updates, config editing, and local/CI deployment.

Related features:

• Site Generation & Frontend Integration Overview
• Site Builder Workflow and Frontend Integration
• Anthropic Integration
• Documentation Chunking and Summarization
• Webhook Integrations

Files Covered

Main Workflows

The CLI supports several core workflows:

1. Initialization

• deepdoc init creates a .deepdoc.yaml config file with sensible defaults for the chosen LLM provider, output directory, and (optionally) chatbot scaffolding.
• Prompts for overwrite if config exists.
• Adds .gitignore entries for generated artifacts.

2. Documentation Generation

• deepdoc generate scans the codebase, plans documentation buckets, generates pages, stages OpenAPI assets, and builds the Fumadocs site.
• Supports full (--force), clean (--clean), and incremental (deepdoc update) modes.
• Handles include/exclude patterns and batch size.

3. Incremental Update

• deepdoc update only regenerates docs for files changed since the last sync, using a smart update strategy (see Pipeline & Generation Engine).
• Optionally triggers deploy.

4. Status & Benchmarking

• deepdoc status shows how many pages were generated, which buckets are stale, and summary stats.
• deepdoc benchmark runs planner/nav quality benchmarks.

5. Local Preview & Deployment

• deepdoc serve launches a local Fumadocs dev server (requires Node.js), optionally scaffolds and starts the chatbot backend.
• deepdoc deploy builds a static export for deployment to any static host.

6. Config Management

• deepdoc config show prints the current config as a table.
• deepdoc config set KEY.PATH VALUE updates a config value without editing YAML.

Main CLI Flow

Participating Endpoints

The CLI itself does not expose HTTP endpoints, but it scaffolds and interacts with services that do. Notably:

• Chatbot Backend: When --with-chatbot is enabled, the CLI scaffolds and (optionally) starts a FastAPI backend for code Q&A. See DeepDoc Chat API Integration.
• Embedding API: If enabled, the CLI ensures the embedding backend is scaffolded. See DeepDoc Embedding API Integration.

For public API endpoints, see Public API Endpoints.

Core Helpers & Business Rules

Command: init() (deepdoc/cli.py:131)

Purpose: Initializes DeepDoc in the current repo, creating .deepdoc.yaml with provider/model/output_dir defaults.

Branching & Validation:

• If .deepdoc.yaml exists, prompts for overwrite unless confirmed.
• Provider-specific defaults:
  • anthropic: model claude-3-5-sonnet-20241022, env ANTHROPIC_API_KEY
  • openai: model gpt-4o, env OPENAI_API_KEY
  • ollama: model ollama/llama3.2, no API key, sets base_url
  • azure: model azure/gpt-4o, env AZURE_API_KEY
• If --with-chatbot, merges in chatbot config from DEFAULT_CHATBOT_CONFIG (deepdoc/chatbot/settings.py).

Example:

deepdoc init --provider openai --model gpt-4o --output-dir documentation

Command: generate() (deepdoc/cli.py:246)

Purpose: Runs the full documentation pipeline.

Branching & Validation:

• If --clean, wipes output and state before generating.
• If DeepDoc-managed output exists and not --force, errors out and suggests update or --force.
• If output dir exists but not DeepDoc-managed, errors unless --clean.
• Handles include, exclude, include_api, batch_size options.

Pipeline Steps:

1. Scan files/symbols/endpoints
2. Plan docs with LLM
3. Generate pages in batches
4. Stage OpenAPI assets
5. Build Fumadocs site

Example:

deepdoc generate --clean --yes

Command: update() (deepdoc/cli.py:362)

Purpose: Incrementally updates docs for changed files.

Branching & Validation:

• Requires prior generate.
• Determines --since commit: explicit > last synced > HEAD~1.
• If generation_mode is "feature_buckets", uses SmartUpdater() (deepdoc/smart_update_v2.py:141).
• If --replan, forces a full replan.
• Optionally triggers deploy.

Example:

deepdoc update --since HEAD~3 --deploy

Command: clean() (deepdoc/cli.py:323)

Purpose: Removes all DeepDoc config, output, and state.

Branching & Validation:

• If nothing to remove, prints a message and exits.
• Prompts for confirmation unless --yes.

Example:

deepdoc clean --yes

Command: status() (deepdoc/cli.py:429)

Purpose: Shows doc generation status, bucket counts, and stale buckets.

Branching & Validation:

• If no plan found, prompts to run generate.
• Uses ledger_summary() (deepdoc/persistence_v2.py:633) for stats.
• Uses find_stale_buckets() (deepdoc/persistence_v2.py:563) to detect out-of-date docs.

Command: serve() (deepdoc/cli.py:547)

Purpose: Runs a local Fumadocs dev server with live reload.

Branching & Validation:

• Requires Node.js >= 18.
• If site/package.json missing, errors and suggests generate.
• If chatbot enabled, starts backend via _start_chatbot_backend().

Example:

deepdoc serve --port 4000

Command: config_show() / config_set() (deepdoc/cli.py:744, deepdoc/cli.py:762)

Purpose: Inspect or update .deepdoc.yaml without editing manually.

Branching & Validation:

• If config missing, errors and suggests init.
• config_set requires a value.

Example:

deepdoc config set llm.provider openai

Helper: _site_dependencies_need_install() (deepdoc/cli.py:674)

Purpose: Checks if site/node_modules or lockfile/stamp are missing or stale.

Branching:

• Returns True if node_modules or package-lock.json missing, or if the hash in .deepdoc-package-sync.json does not match the current package.json.

Tested in: tests/test_cli_serve.py

Helper: _start_chatbot_backend() (deepdoc/cli.py:889)

Purpose: Scaffolds and starts the chatbot backend if enabled and not using an external URL.

Branching:

• If backend.base_url is set, skips local spawn.
• If backend scaffold missing, prints warning and continues without chat.
• Picks an available port, warns if preferred port is busy.

State Transitions

The CLI manages several stateful artifacts:

• .deepdoc.yaml: Project config (created/updated/removed)
• docs/ (or custom output): Generated Markdown docs
• site/: Fumadocs site scaffold and build output
• .deepdoc/: Plan, ledger, and sync state
• chatbot_backend/: Chatbot backend scaffold (if enabled)

State transitions:

Integrations Involved

• LLM Providers: Used for planning/generation (anthropic, openai, ollama, azure). See Anthropic Integration.
• Fumadocs: Site generator and frontend integration. See Site Generation & Frontend Integration Overview.
• Chatbot Backend: Optional FastAPI backend for code Q&A. See DeepDoc Chat API Integration.
• Embedding API: Optional backend for vector search. See DeepDoc Embedding API Integration.
• Webhooks: CLI scaffolds integration points. See Webhook Integrations.

Configuration & Environment

Key config options (in .deepdoc.yaml):

Environment variables (set via .env or shell):

• OPENAI_API_KEY, ANTHROPIC_API_KEY, AZURE_API_KEY: Used for LLM access, depending on provider.

Edge Cases & Failure Modes

• Config Exists: init prompts before overwriting .deepdoc.yaml.
• Output Directory Not Managed: If output dir exists but is not DeepDoc-managed, generate errors unless --clean is used.
• Node.js Missing: serve and deploy require Node.js >= 18. If missing, errors out.
• Chatbot Port Busy: If the preferred port for the chatbot backend is busy, picks another and warns.
• Stale Buckets: status reports buckets as stale if source files are changed, deleted, or output is missing.
• Missing Config: Most commands error and suggest init if .deepdoc.yaml is missing.
• Dependency Sync: If site/node_modules or lockfiles are missing or stale, triggers npm install.

Diagrams

CLI Main Flow

Quick Reference

Constants, Enums & Status Values

LLM Providers (init):

• "anthropic", "openai", "ollama", "azure"

Config keys affecting behavior:

• llm.provider, llm.model, llm.api_key_env, llm.base_url, chatbot.enabled

See Also

• Setup & Getting Started
• Pipeline & Generation Engine
• Site Generation & Frontend Integration Overview
• Site Builder Workflow and Frontend Integration
• Anthropic Integration
• Documentation Chunking and Summarization
• Webhook Integrations
• DeepDoc Chat API Integration
• DeepDoc Embedding API Integration