@openpkg-ts/cli

CLI for TypeScript API extraction and documentation generation.

Install

``bash
npm install -g @openpkg-ts/cli


or use directly


npx @openpkg-ts/cli
`

Command Structure

Commands organized under openpkg spec and openpkg docs. Legacy commands work as aliases.

`bash
openpkg spec snapshot ./src/index.ts -o spec.json
openpkg spec validate spec.json

openpkg docs init
openpkg docs generate spec.json -o ./docs
openpkg docs add function-section
`

---

Spec Commands

$3

`bash
openpkg list src/index.ts
`

Output: JSON array of { name, kind, file, line, description }

$3

`bash
openpkg get src/index.ts createClient
`

Output: JSON with { export, types } - full spec for the export plus referenced types.

$3

`bash
openpkg spec snapshot src/index.ts -o openpkg.json
openpkg spec snapshot src/index.ts -o - # stdout
openpkg spec snapshot src/index.ts --max-depth 4 --runtime --verify
openpkg spec snapshot src/index.ts --only "use,create" --ignore "*Internal"
`

| Flag | Description |
|------|-------------|
| -o, --output | Output file (default: openpkg.json, - for stdout) |
| --max-depth | Max type depth (default: 4) |
| --skip-resolve | Skip external type resolution |
| --runtime | Enable Standard Schema runtime extraction (Zod, Valibot) |
| --only | Filter exports (comma-separated, wildcards) |
| --ignore | Ignore exports (comma-separated, wildcards) |
| --verify | Exit 1 if any exports fail |

$3

`bash
openpkg spec validate openpkg.json
openpkg spec validate openpkg.json --version 1.0
`

$3

`bash
openpkg spec diagnostics openpkg.json
`

$3

`bash
openpkg spec filter openpkg.json --kind function,class
openpkg spec filter openpkg.json --has-description -o documented.json
openpkg spec filter openpkg.json --search "user" --summary
openpkg spec filter openpkg.json --deprecated --quiet | jq '.exports[].name'
`

| Flag | Description |
|------|-------------|
| --kind | Filter by kinds (comma-separated) |
| --name | Filter by exact names (comma-separated) |
| --id | Filter by export IDs (comma-separated) |
| --tag | Filter by tags (comma-separated) |
| --deprecated | Only deprecated exports |
| --no-deprecated | Exclude deprecated exports |
| --has-description | Only exports with descriptions |
| --missing-description | Only exports without descriptions |
| --search | Search name/description (case-insensitive) |
| --module | Filter by source file path (contains) |
| -o, --output | Output file (default: stdout) |
| --summary | Only output matched/total counts |
| --quiet | Output raw spec only (no wrapper) |

$3

`bash
openpkg spec diff old.json new.json
openpkg spec diff old.json new.json --summary
`

$3

Exit 1 if breaking changes found.

`bash
openpkg spec breaking old.json new.json
`

$3

`bash
openpkg spec semver old.json new.json
`

$3

`bash
openpkg spec changelog old.json new.json
openpkg spec changelog old.json new.json --format json
`

---

Docs Commands

$3

Initialize docs configuration.

`bash
openpkg docs init
`

Creates openpkg.config.json with default settings.

$3

Generate documentation from spec.

`bash


Markdown (default)

openpkg docs generate openpkg.json -o api.md

React layout (single layout + spec JSON, add components via registry)

openpkg docs generate openpkg.json -f react -o ./app/api

HTML

openpkg docs generate openpkg.json -f html -o api.html

JSON (simplified structure)

openpkg docs generate openpkg.json -f json

Split: one file per export

openpkg docs generate openpkg.json --split -o docs/api/

With adapter

openpkg docs generate openpkg.json -a fumadocs -o docs/api/

From stdin

openpkg spec snapshot src/index.ts -o - | openpkg docs generate - -f md
`

| Flag | Description |
|------|-------------|
| -o, --output | Output file or directory (default: stdout) |
| -f, --format | Format: md, json, html, react (default: md) |
| --split | One file per export (requires -o as directory) |
| -a, --adapter | Use adapter: fumadocs, raw (default: raw) |

$3

Add components from shadcn-compatible registry.

`bash
openpkg docs add function-section
openpkg docs add class-section interface-section
openpkg docs add export-card param-table signature
`

$3

List available registry components.

`bash
openpkg docs list
`

16 components available: layouts, sections, primitives.

$3

View component details and dependencies.

`bash
openpkg docs view function-section
`

---

Pipelines

Commands are composable via stdin/stdout:

`bash


Extract and generate docs

openpkg spec snapshot src/index.ts -o - | openpkg docs generate - -f md > api.md

Extract, verify, then diff

openpkg spec snapshot src/index.ts --verify -o new.json
openpkg spec diff baseline.json new.json --summary
`

Programmatic Use

`typescript
import { getExport, listExports } from '@openpkg-ts/sdk';

// Same primitives as CLI
const { exports } = await listExports({ entryFile: './src/index.ts' });
const { export: spec } = await getExport({ entryFile: './src/index.ts', exportName: 'myFunc' });
``

License

MIT