or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build.mdcli-commands.mdindex.mdinput-processing.mdlint.mdoutput-formats.mdutilities.md
tile.json

cli-commands.mddocs/

CLI Commands

Command-line interface for documentation generation, linting, and README integration. Provides three main commands with comprehensive options for different documentation workflows.

Capabilities

Build Command

Generate documentation from source files in various output formats.

documentation build [input..] [options]

Options:
  -f, --format <format>         Output format: html, md, json, remark
  -o, --output <path>           Output directory or file (default: stdout)
  -t, --theme <theme>           Theme for HTML output
  --project-name <name>         Project name (inferred from package.json)
  --project-version <version>   Project version (inferred from package.json)
  --project-description <desc>  Project description (inferred from package.json)
  --project-homepage <url>      Project homepage (inferred from package.json)
  --favicon <path>              Favicon used in HTML output
  -g, --github                  Enable GitHub source linking
  --shallow                     Skip dependency resolution
  -a, --access <levels>         Access levels: public, private, protected, undefined
  --external <patterns>         External modules to include (string/glob pattern)
  -c, --config <path>           Configuration file path
  --document-exported           Document only exported values
  -pe, --parse-extension <exts> File extensions to parse as source code
  -re, --require-extension <exts> Additional extensions for require() search
  --markdown-toc                Generate table of contents in Markdown (default: true)
  --markdown-toc-max-depth <n>  Max depth for Markdown TOC (default: 6)
  --sort-order <order>          Sorting: source, alpha, kind, access, memberof
  --infer-private <pattern>     Regex pattern for private members
  --babel <path>                Path to .babelrc or babel.options.js config
  --no-package, -np             Don't use package.json for configuration
  --resolve <algorithm>         Dependency resolution: browser (default), node
  -w, --watch                   Watch files and rebuild on changes

Usage Examples:

# Generate Markdown documentation
documentation build index.js -f md > API.md

# Generate HTML documentation with GitHub integration
documentation build src/** -f html --github -o docs

# Document only public APIs
documentation build lib/ -f html --access public -o public-docs

# Generate JSON for programmatic use
documentation build src/ -f json -o api.json

# Document TypeScript files
documentation build src/ --parse-extension ts -f html -o docs

# Shallow documentation (no dependency resolution)
documentation build index.js --shallow -f md

# Custom theme and project information
documentation build src/ -f html -t custom-theme --project-name "My Project" --project-version "1.0.0"

# Include external dependencies
documentation build src/ -f html --external "lodash.*,express"

# Document only exported values
documentation build lib/index.js --document-exported -f md

# Generate with table of contents and custom depth
documentation build src/ -f md --markdown-toc --markdown-toc-max-depth 3

# Watch mode for development
documentation build src/ -f html -o docs/ --watch

# Use custom babel configuration
documentation build src/ -f html --babel .babelrc.docs.js

# Custom dependency resolution
documentation build src/ -f html --resolve node

# Multiple file extensions
documentation build src/ -f html --parse-extension ts,tsx --require-extension vue

Lint Command

Validate JSDoc syntax and documentation quality.

documentation lint [input..] [options]

Options:
  --shallow                     Skip dependency resolution
  --external <patterns>         External modules to include (string/glob pattern)
  -c, --config <path>           Configuration file path
  -pe, --parse-extension <exts> File extensions to parse as source code
  -re, --require-extension <exts> Additional extensions for require() search
  --infer-private <pattern>     Regex pattern for private members
  --babel <path>                Path to .babelrc or babel.options.js config
  --no-package, -np             Don't use package.json for configuration
  --resolve <algorithm>         Dependency resolution: browser (default), node
  -a, --access <levels>         Access levels to validate: public, private, protected, undefined
  --document-exported           Validate only exported values
  --sort-order <order>          Sorting: source, alpha, kind, access, memberof

Usage Examples:

# Lint JavaScript files
documentation lint src/

# Lint specific file
documentation lint util.js

# Lint TypeScript files
documentation lint src/ --parse-extension ts

# Shallow linting (no dependencies)
documentation lint index.js --shallow

# Lint with external modules
documentation lint src/ --external "lodash,express"

# Custom private member detection
documentation lint src/ --infer-private "^_"

# Use in CI/CD pipeline
documentation lint src/ || exit 1

README Command

Update README.md files with generated documentation.

documentation readme [input..] [options]

Options:
  -s, --section <name>          README section to update (required)
  --readme-file <path>          Path to README file (default: auto-detected)
  -d, --diff-only               Check if README matches, exit nonzero if not
  -q, --quiet                   Quiet mode: no output messages or diff
  -g, --github                  Enable GitHub source linking
  --shallow                     Skip dependency resolution
  -a, --access <levels>         Access levels: public, private, protected, undefined
  --external <patterns>         External modules to include (string/glob pattern)
  -c, --config <path>           Configuration file path
  --document-exported           Document only exported values
  -pe, --parse-extension <exts> File extensions to parse as source code
  -re, --require-extension <exts> Additional extensions for require() search
  --markdown-toc                Generate table of contents (default: true)
  --markdown-toc-max-depth <n>  Max depth for Markdown TOC (default: 6)
  --sort-order <order>          Sorting: source, alpha, kind, access, memberof
  --infer-private <pattern>     Regex pattern for private members
  --babel <path>                Path to .babelrc or babel.options.js config
  --no-package, -np             Don't use package.json for configuration
  --resolve <algorithm>         Dependency resolution: browser (default), node
  --project-name <name>         Project name (inferred from package.json)
  --project-version <version>   Project version (inferred from package.json)
  --project-description <desc>  Project description (inferred from package.json)
  --project-homepage <url>      Project homepage (inferred from package.json)

Usage Examples:

# Update API section in README.md
documentation readme index.js --section=API

# Update custom section with GitHub links
documentation readme src/ --section="Public API" --github

# Update README with only public APIs
documentation readme lib/ --section=API --access public

# Custom README file location
documentation readme src/ --readme-file docs/README.md --section=API

# Document exported values only
documentation readme lib/index.js --section=API --document-exported

# Include table of contents
documentation readme src/ --section=API --markdown-toc

# TypeScript support
documentation readme src/ --section=API --parse-extension ts

# Custom sorting
documentation readme src/ --section=API --sort-order alpha

# Check if README needs updates (CI/CD)
documentation readme src/ --section=API --diff-only

# Quiet mode for scripts
documentation readme src/ --section=API --quiet

# Custom README file location
documentation readme src/ --section=API --readme-file docs/API.md

# Use custom babel config
documentation readme src/ --section=API --babel .babelrc.docs.js

Configuration File

Use a configuration file to avoid repeating command-line options:

documentation.yml:

# Input configuration
inputs:
  - src/
  - lib/

# Output configuration
output: docs/
format: html
theme: default

# Project information
name: My Project
version: 1.0.0

# Processing options
github: true
access:
  - public
  - protected
external:
  - lodash.*
  - express

# File handling
parseExtension:
  - ts
  - tsx
inferPrivate: "^_"

# Output options
markdownToc: true
documentExported: false

documentation.json:

{
  "inputs": ["src/"],
  "output": "docs/",
  "format": "html",
  "theme": "default",
  "name": "My Project",
  "version": "1.0.0",
  "github": true,
  "access": ["public"],
  "external": ["lodash.*"],
  "parseExtension": ["ts"],
  "markdownToc": true
}

Use configuration file:

documentation build --config documentation.yml
documentation lint --config documentation.json

Global Installation

Install documentation.js globally for command-line usage:

# Install globally
npm install -g documentation

# Verify installation
documentation --version

# Get help
documentation --help
documentation build --help

Local Project Usage

Use documentation.js in project scripts:

package.json:

{
  "scripts": {
    "docs:build": "documentation build src/ -f html -o docs/",
    "docs:md": "documentation build src/ -f md > API.md",
    "docs:lint": "documentation lint src/",
    "docs:readme": "documentation readme src/ --section=API",
    "docs:watch": "documentation build src/ -f html -o docs/ --watch"
  },
  "devDependencies": {
    "documentation": "^14.0.3"
  }
}

Run with npm:

npm run docs:build
npm run docs:lint
npm run docs:readme

Format-Specific Options

HTML Format Options

documentation build src/ -f html \
  --theme default \
  --name "My Project" \
  --version "1.0.0" \
  --github \
  -o docs/

HTML-specific features:

  • Interactive navigation: Automatic sidebar generation
  • Search functionality: Client-side search
  • Responsive design: Mobile-friendly layouts
  • Syntax highlighting: Code example highlighting
  • Source linking: GitHub integration

Markdown Format Options

documentation build src/ -f md \
  --markdown-toc \
  --access public \
  --github > API.md

Markdown-specific features:

  • Table of contents: Optional TOC generation
  • GitHub Flavored Markdown: Compatible with GitHub
  • Clean formatting: Well-structured output
  • Cross-references: Internal linking

JSON Format Options

documentation build src/ -f json \
  --access public \
  -o api.json

JSON-specific features:

  • Complete data: All parsed information
  • Programmatic access: Machine-readable format
  • Custom processing: Use with other tools
  • API integration: Serve via REST APIs

Exit Codes

Documentation.js uses standard exit codes:

  • 0: Success - no errors or lint issues
  • 1: Error - processing failed or lint issues found
  • 2: Invalid usage - incorrect command-line arguments

CI/CD Integration:

# Fail build on lint issues
documentation lint src/ || exit 1

# Fail build on documentation generation errors
documentation build src/ -f html -o docs/ || exit 1

Environment Variables

Configure behavior with environment variables:

# Set default configuration file
export DOCUMENTATION_CONFIG=documentation.yml

# Enable debug output
export DEBUG=documentation:*

# Set custom theme directory
export DOCUMENTATION_THEME_PATH=/path/to/themes

Watch Mode

Monitor files for changes and rebuild automatically:

# Watch for changes (requires additional tooling)
npx chokidar "src/**/*.js" -c "documentation build src/ -f html -o docs/"

# Using nodemon
npx nodemon --watch src/ --ext js --exec "documentation build src/ -f html -o docs/"

Error Handling

Common error scenarios and solutions:

File Not Found

documentation build nonexistent.js
# Error: Input file not found

Invalid Configuration

documentation build src/ --access invalid
# Error: Invalid access level

Module Resolution Issues

documentation build src/ --external "invalid-pattern[*"
# Error: Invalid regex pattern

Permission Errors

documentation build src/ -o /root/docs/
# Error: Permission denied

Performance Tips

Optimize documentation generation for large projects:

# Use shallow processing for faster builds
documentation build src/ --shallow -f html -o docs/

# Exclude test files
documentation build "src/**/!(*.test).js" -f html -o docs/

# Document only public APIs
documentation build src/ --access public -f html -o docs/

# Use specific file patterns
documentation build "src/api/*.js" -f html -o docs/