docs-cli

A CLI that imports documentation from a centralized docs registry into your project. Think npx shadcn add button, but for docs.

npx docs-cli list                  # see what's available
npx docs-cli add testing           # add a single doc
npx docs-cli add architecture      # add an entire category

Installation

For Local Development/Testing

To install the CLI locally for development or testing:

# Clone the repository
git clone https://github.com/samspoerl/docs-cli
cd docs-cli

# Install dependencies and build
npm install
npm run build

# Link globally to make available as a command
npm link

After running npm link, the docs-cli command will be available system-wide. You can now use it in any project without npx:

docs-cli list
docs-cli add testing

Future Installation Options

npm: This package is planned to be published to npm. Once available, you'll be able to install it with:

npm install -g docs-cli
# or use with npx without installation
npx docs-cli list

Private Package Registry: If your organization uses a private package manager (e.g., Azure Artifacts, GitHub Packages, or npm Enterprise), you can publish this package there for internal distribution.

How it works

The docs themselves live in a separate repository — the CLI is just the delivery mechanism. This is the same pattern shadcn uses: the npm package contains no component code, it just fetches from a remote registry at runtime.

Why separate?

• Docs change constantly, the CLI doesn't. Fixing a typo in a guide shouldn't require a new npm release. The docs repo is the source of truth — push to main and every project gets the update on next add.
• The docs repo stays useful on its own. People can browse it on GitHub, link to it in PRs, and read it without the CLI.
• The CLI stays lightweight. It's a thin fetch → write tool with no bundled content.

The docs repo hosts a registry.json that describes all available docs. The CLI fetches that manifest, resolves your request, downloads the files, and writes them into your project.

Setup

1. Create a docs repo

Your docs repo needs a registry.json at the root:

{
  "baseUrl": "https://raw.githubusercontent.com/YOUR_ORG/YOUR_DOCS_REPO/main",
  "docs": [
    {
      "name": "testing",
      "description": "Testing architecture and patterns",
      "category": "architecture",
      "files": ["docs/architecture/testing.md"]
    },
    {
      "name": "coding-principles",
      "description": "Core coding principles",
      "category": "standards",
      "files": ["docs/standards/coding-principles.md"]
    }
  ]
}

2. Configure your project

Option A: Global Configuration (Recommended for Personal Use)

Set environment variables to configure all your projects at once:

# PowerShell
$env:DOCS_CLI_REGISTRY_URL = "https://raw.githubusercontent.com/YOUR_ORG/YOUR_DOCS_REPO/main/registry.json"
$env:DOCS_CLI_OUTPUT_DIR = "docs"
$env:DOCS_CLI_GITHUB_TOKEN = "github_pat_your_personal_access_token"

# cmd
set DOCS_CLI_REGISTRY_URL=https://raw.githubusercontent.com/YOUR_ORG/YOUR_DOCS_REPO/main/registry.json
set DOCS_CLI_OUTPUT_DIR=docs
set DOCS_CLI_GITHUB_TOKEN=github_pat_your_personal_access_token

# Linux/Mac (~/.bashrc or ~/.zshrc)
export DOCS_CLI_REGISTRY_URL="https://raw.githubusercontent.com/YOUR_ORG/YOUR_DOCS_REPO/main/registry.json"
export DOCS_CLI_OUTPUT_DIR="docs"
export DOCS_CLI_GITHUB_TOKEN="github_pat_your_personal_access_token"

This is ideal when you always use the same docs registry across projects. No docs-cli.json file needed.

Option B: Local Configuration (Per-Project)

Create a docs-cli.json in your project root:

{
  "registryUrl": "https://raw.githubusercontent.com/YOUR_ORG/YOUR_DOCS_REPO/main/registry.json",
  "outputDir": "docs"
}

For private docs repos, also create a .env file:

DOCS_CLI_GITHUB_TOKEN=github_pat_your_personal_access_token

The CLI will automatically load this file and use the token to authenticate requests. Create a fine-grained personal access token with read-only access to your docs repo.

Configuration Hierarchy

Settings are resolved in this order (highest priority first):

1. Local docs-cli.json — overrides everything
2. Environment variables — global defaults
3. Built-in defaults — outputDir: "docs"

This means you can set global defaults via environment variables, then override them per-project with docs-cli.json when needed (e.g., to point to a different registry).

3. Use it

# List available docs
npx docs-cli list

# Add specific docs
npx docs-cli add testing coding-principles

# Add all docs in a category
npx docs-cli add architecture

# Write to a custom directory
npx docs-cli add testing -o .docs

Development

npm install
npm run build        # compile with tsup
npm run dev          # watch mode
npm run typecheck    # type-check without emitting
npm test             # run tests