Doku.sh CLI

Doku generates external-facing developer documentation from a codebase and opens it as a documentation portal at https://doku.sh.

The default audience is developers using or integrating with the project from the outside. Doku first determines whether the repository describes an installable product/CLI or an API-first service, then builds the overview and quickstart around the public path users are actually expected to take. Internal engineering material is opt-in with --internal.

Install

npm install -g @wundercorp/doku

Generate external developer docs

From the codebase you want to document:

doku portal .

Or generate without opening the browser:

doku gen . --output doku.docs.json

When you know the public API base URL, pass it explicitly:

doku gen . --base-url https://api.example.com

Then open the generated portal:

doku open ./doku.docs.json --site https://doku.sh

External-first behavior

Without --internal, Doku generates documentation intended for external users and developers.

The generated portal can include:

• product-aware overview and quickstart
• detected public install commands and CLI entrypoints
• detected HTTP endpoints when the repository presents a public API
• API authentication and API-key guidance
• cURL request examples
• JavaScript examples
• Python examples
• Go examples
• Ruby examples
• PHP examples
• Java examples
• hand-written public Markdown, MDX, and text documentation
• API/reference documentation already present in the repository
• external-facing llms-full.txt context

The default portal does not include:

• local package scripts
• build and test commands intended for maintainers
• dependency inventories
• project structure
• source declaration reference pages
• source file bodies
• deployment documentation
• infrastructure documentation
• internal runbooks and operations documentation
• detailed configuration/source context

Product onboarding detection

Doku inspects public repository surfaces before deciding what the generated Overview and Quickstart should teach. It looks at the root README, quickstart/install docs, public landing-page HTML, installer entrypoints, package metadata, and Python/Node CLI declarations.

For an installable product, Doku prefers the real end-user flow, for example:

curl -fsSL https://product.example.com/install.sh | bash
product

Platform-specific public installers such as PowerShell are preserved when detected. In this mode Doku does not publish speculative generated API/authentication pages solely because framework routes or third-party provider URLs exist somewhere in the source tree. Generated API reference pages become primary when the project is API-first or a public API origin is configured/detected confidently.

Root README.md content is used as generation context instead of being added as a second redundant Overview page. Nested README files receive titles from their parent component (docs/middleware/README.md becomes Middleware) so navigation does not fill up with indistinguishable README entries. Common README HTML wrappers for links, badges, and centered blocks are normalized into portal-safe Markdown.

API detection

Doku scans source code to infer route declarations without embedding implementation bodies in the generated external docs.

It recognizes common route patterns used by JavaScript/TypeScript servers, Express-style routers, Fastify/Hono-style routers, Flask/FastAPI-style decorators, Go routers, Spring mappings, Laravel routes, Rails routes, Next.js App Router API routes, and Next.js Pages Router API routes.

When route semantics such as request fields, response schemas, query parameters, or error responses cannot be inferred safely, Doku does not invent them.

Authentication and API keys

Doku attempts to detect common public authentication patterns such as:

Authorization: Bearer <API_KEY>
x-api-key: <API_KEY>

It can also detect common API-key environment variable names without exposing their values.

For exact output, configure the authentication surface from the CLI:

doku gen . \
  --base-url https://api.example.com \
  --auth-header Authorization \
  --auth-scheme Bearer

For a header-only API key:

doku gen . \
  --base-url https://api.example.com \
  --auth-header x-api-key \
  --auth-scheme none

Optional package configuration

A Node.js project can provide public documentation defaults in package.json:

{
  "doku": {
    "public": {
      "baseUrl": "https://api.example.com",
      "auth": {
        "header": "Authorization",
        "scheme": "Bearer",
        "apiKeyName": "EXAMPLE_API_KEY"
      }
    }
  }
}

CLI flags override these values.

Internal mode

Pass --internal only when the generated documentation is intended for trusted internal use:

doku gen . --internal

Internal mode adds an Internal portal tab containing the project-oriented material that is intentionally hidden from external docs, including local setup, scripts, dependencies, project structure, deployment/infrastructure documentation, and source declaration references.

doku gen --internal still does not embed source bodies or configuration values in the portal bundle.

For detailed internal LLM source context, use:

doku llms . --internal --output llms-full.txt

Without --internal, doku llms remains external-facing:

doku llms . --output llms-full.txt

Documentation filtering

Doku excludes documentation files that are clearly internal, operational, deployment-oriented, or dominated by implementation details that an API consumer should not need. In addition to path and filename checks, Doku inspects documentation content for infrastructure and operator signals such as Terraform, cloud resource wiring, provider credentials, secret-management procedures, internal state stores, recovery procedures, and provider-adapter implementation material.

Within otherwise public Markdown documents, internal sections and infrastructure-oriented code blocks or lines are removed from the external copy. This allows an authentication or API guide to keep its public integration instructions while omitting runtime variables, Terraform commands, operator configuration, secret rotation, and similar internal details.

Use --internal when those excluded pages and sections are intentionally being generated for trusted engineers.

The original repository files are never modified.

Safety model

Doku ignores common sensitive and local-only files during project discovery, including environment files, credentials, private keys, hidden files, operating-system metadata, caches, generated artifacts, lock files, and temporary files.

External generation uses source code only to infer safe metadata such as HTTP routes, authentication header names, API-key environment variable names, and public declarations when internal mode is enabled. Source bodies and secret values are not copied into external docs.

Detailed source context is available only through the explicit combination:

doku llms . --internal

CLI

doku portal [source-directory] --output doku.docs.json --site https://doku.sh
doku gen [source-directory] --output docs.json --llms-output llms-full.txt
doku llms [source-directory] --output llms-full.txt
doku pack [docs-or-project-directory] --output doku.docs.json
doku open <docs-file-or-url> --site https://doku.sh
doku url <docs-json-or-llms-url> --site https://doku.sh
doku sudoku --site https://su.doku.sh

Useful generation controls:

doku gen . --base-url https://api.example.com
doku gen . --auth-header Authorization --auth-scheme Bearer
doku gen . --mpp-base-url https://mpp.example.com
doku gen . --internal
doku gen . --title "Acme API"
doku gen . --max-file-bytes 120000 --max-total-bytes 1800000
doku gen . --no-llms
doku gen . --stdout

Doku site spec

Generated documentation uses the Doku v2 site spec:

{
  "schema": "doku.sh/site-spec/v2",
  "schemaVersion": 2,
  "name": "Acme API",
  "doku": {
    "audience": "external",
    "api": {
      "baseUrl": "https://api.example.com",
      "endpointCount": 4,
      "authHeader": "Authorization",
      "authScheme": "Bearer",
      "mppDetected": true,
      "mppBaseUrl": "https://mpp.example.com",
      "mppEndpointCount": 3
    }
  },
  "navigation": {
    "tabs": []
  },
  "pageMeta": {},
  "pagesContent": {}
}

navigation.tabs provides portal-level navigation. pagesContent maps page paths to Markdown bodies. pageMeta supplies descriptions and generated/manual metadata. The documentation header includes a persistent Search all docs… field immediately before Share URL, with / as the keyboard shortcut.

Legacy and existing docs

doku pack remains available for existing docs folders and legacy docs.json layouts:

doku pack ./existing-docs --output doku.docs.json

Doku can also open existing llms-full.txt URLs directly:

doku open https://example.com/llms-full.txt --site https://doku.sh

License

Apache-2.0

Machine Payments Protocol

Doku detects MPP payment surfaces from public docs, custom HTTP dispatchers, and OpenAPI-shaped source definitions. Use --mpp-base-url only when the dedicated MPP origin cannot be inferred. MPP endpoints are external-facing by default; deployment and operator material still requires --internal.

Deployment ownership

The CLI does not ship or manage Doku's AWS infrastructure. It generates documentation locally and uses the deployed portal at https://doku.sh for import/share flows.

The static portal, /api/imports backend, Lambda, S3, CloudFront, and DNS infrastructure are owned by the website/infrastructure side of the same Doku repository. Terraform stays at the repository root and is never shipped inside the npm CLI package.

Publishing from the Doku repository

The npm package lives in cli/ inside the main Doku repository. From the repository root, publish it with:

bash scripts/deploy-cli.sh

The CLI publish path does not use Terraform. Use --dry-run to validate the npm package without publishing.