docspack v1.5.0
Search ⌘K
Commands

The docspack command line

Every command, option and exit status, generated from the document the CLI's own parser and --help are built from. What each command reads, writes or deletes is stated on it.

Install
npm i -D docspack
Version
1.5.0
Commands
23

For an agent: /cli.txt — every command in one line each. One command: /cli/<command>.md . The document itself: /cmdspec.json, in the cmdspec format.

docspack

Local, version-locked documentation for AI agents

sh
docspack <command> [options]

Options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

  • -v, --version

    Show the version

  • --cmdspec

    Print this program's own cmdspec document, as JSON

Commands

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

docspack sync

Index the docs packages this project depends on

Reads node_modules and indexes every @vendor/docspack and @docspack-community/ package this project declares. Makes no network requests.

It also reads each installed library’s own type declarations and indexes one entry per exported name. Half of a well-documented library’s exports are mentioned in no documentation anyone published, and those declarations are the only local answer for them. They are looked up by name, never ranked against prose, so they cannot crowd out the documentation that does exist.

A library that describes its own command line, with "cmdspec" in its package.json, has that description indexed as well, for the version installed.

sh
docspack sync [options]

Effects

readwrite

effects: read, write; idempotent

Options

  • --force

    re-index packages already in the store

  • --no-artifacts

    skip the declarations derived from installed libraries

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack sync
$ docspack sync --force
$ docspack sync --no-artifacts

Build a command line

Inherited options

Use a different index

Run in a different directory

sh
docspack sync

docspack ask

Answer from the local index — the command to give an agent

Answers from the installed versions, in the Markdown an agent should read.

When the question names something an installed library exports and no documentation mentions, the answer leads with that name’s declaration from the installed build and says the documentation does not cover it. Ranking alone cannot tell that apart from a match. A question that names an endpoint (POST /v1/charges) or a command (git remote add) gets that operation or command first.

sh
docspack ask <question>... [options]

Effects

read

effects: read; idempotent

Arguments

  • <question>...required

    words are joined with spaces

Options

  • -p, --package <s>

    only packages whose name contains this text

  • --limit <n>integer; at least 1; default 3

    maximum chunks to return

  • --max-tokens <n>integer; at least 1; default 3000

    token ceiling for the result set

  • --all

    search the whole store, not just this project

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Input and output

  • stdout

    text/markdown, the answer

    application/json, the chunks and their scores with --json

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly
  • 3nothing matched, and a docs package is installed but not indexed

    Run `docspack sync`, then ask again.

  • 4nothing matched, and everything installed is already indexed

Examples

sh
$ docspack ask "how do I verify a webhook signature"

# Look in one package only, and return more
$ docspack ask "webhook signature" --package stripe --limit 5

Build a command line

One per line.

only packages whose name contains this text

maximum chunks to return

token ceiling for the result set

Inherited options

Use a different index

Run in a different directory

sh
docspack ask <question>...

docspack index

Index this project's own sources, so an agent can ask them instead of reading them

For a corpus this project already has rather than one somebody published: notes, an export, rows out of a query. Nothing is written but the index, in .docspack/local.db, which is a plaintext copy of whatever was indexed and is gitignored on the tool’s behalf.

Records arrive as JSON so no database driver is needed: sqlite3 -json … | docspack index --from-json -. A record with an id becomes one chunk under that id, because a row’s identity is its key.

What was indexed is recorded with each source’s size, mtime and hash, so a re-run does nothing when nothing has changed and recall can say when an answer may be superseded.

--repo indexes the repository at the working directory as two corpora. @local/repo-docs holds every Markdown file git tracks or would track, minus changelogs and test fixtures. @local/repo-code is a map of the code: one entry per top-level declaration holding its signature, doc comment and file:line, never its body, and one entry per workspace package. git decides what belongs to the project, so node_modules and build output are never read. They are separate because in one corpus the prose outranks the map; ask one with recall --name.

sh
docspack index [options]

Effects

readwrite

effects: read, write; idempotent

Options

  • --repo

    this git repository's Markdown and a map of its code, as two corpora

  • --from <dir>directory

    directory of Markdown to package

  • --from-json <file>file; - means standard input or output

    JSON records to index, or `-` for standard input

  • --name <s>default derived from the source

    name for the corpus

  • --force

    re-index even when no source has changed

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Constraints

  • at most one of: --repo, --from

  • at most one of: --repo, --from-json

  • at most one of: --repo, --name

Input and output

  • stdin

    application/json, an array of records, each with text and optionally an id and a title with --from-json=-

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
# Index this repository's docs and a map of its code
$ docspack index --repo

$ docspack index --from ./notes

# Index rows straight out of a database
$ sqlite3 -json shop.db 'select id, title, body as text from posts' | docspack index --from-json -

Build a command line

directory of Markdown to package

JSON records to index, or `-` for standard input

name for the corpus

Inherited options

Use a different index

Run in a different directory

sh
docspack index

docspack recall

Answer from this project's indexed corpus, not from its dependencies

Separate from ask on purpose. ask answers from the versions this project installed, and a working corpus is never one of them — so a corpus cannot reach an answer about a dependency, and a dependency cannot reach an answer about your notes.

An answer leads with a warning when a source has changed since it was indexed.

sh
docspack recall <question>... [options]

Effects

read

effects: read; idempotent

Arguments

  • <question>...required

Options

  • --name <s>default every corpus

    search one corpus only, by name, with or without `@local/`

  • --limit <n>integer; at least 1; default 3

    maximum chunks to return

  • --max-tokens <n>integer; at least 1; default 3000

    token ceiling for the result set

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1nothing matched
  • 2the command was used wrongly

Examples

sh
$ docspack recall "what did we decide about retries"

# Ask the map of this repository's code, after `index --repo`
$ docspack recall --name repo-code "where are requests forwarded to the backend"

Build a command line

One per line.

search one corpus only, by name, with or without `@local/`

maximum chunks to return

token ceiling for the result set

Inherited options

Use a different index

Run in a different directory

sh
docspack recall <question>...

docspack list

Show this project's docs packages and their index state

Coverage is mechanical: the exported names a library declares, against the names its documentation mentions anywhere. It is reported, never gated on — a page listing every export and explaining none would score full marks.

sh
docspack list [options]

Effects

read

effects: read; idempotent

Options

  • --coverage

    how much of each documented library's exports the prose mentions

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack list
$ docspack list --coverage
$ docspack list --json

Build a command line

Inherited options

Use a different index

Run in a different directory

sh
docspack list

docspack agent

Wire docspack into the agent tooling this project already uses

install writes a marked block into AGENTS.md or CLAUDE.md — whichever the project already has — and a skill into .claude/skills/docspack/ when the project uses Claude Code. Everything outside the markers is left alone, and re-running rewrites the block rather than appending a second copy. With no subcommand, agent installs.

--recipe factory writes a way of working on top: rules for autonomous sessions in the block, a second skill, a SessionStart hook that indexes .factory/knowledge/ for recall, and a .factory/ layout of templates. Those .factory/ files are seeded — written once when absent and never again — so filling one in is never reported as drift.

--recipe repo is for working in an ordinary repository: rules in the block that send the agent to recall --name repo-code before it reads files to find something, four lines asking for fewer, larger tool calls, a docspack-repo skill, and a SessionStart hook that runs index --repo.

check writes nothing and exits non-zero when the wiring is missing or out of date, so CI notices a pasted instruction that has drifted from what the tool now does. It also prints what each instruction file costs, since the file is sent again on every turn, and over 1,000 tokens names its three largest sections.

sh
docspack agent [<command>] [options]

Effects

readwrite

effects: read, write; idempotent

Options

  • --recipe <name>one of deps, factory, repo

    the way of working to write; read back from the block when omitted

  • --feedback

    also include recording documentation problems

  • --hooks

    add a SessionStart hook that keeps the index in step

  • --mcp

    add the MCP server to .mcp.json

  • --dry-runeffects become: read

    print what would be written and write nothing

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Commands

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack agent install --feedback --hooks

Build a command line

the way of working to write; read back from the block when omitted

Inherited options

Use a different index

Run in a different directory

sh
docspack agent

docspack agent install

Write the docspack block into AGENTS.md or CLAUDE.md

sh
docspack agent install [options]

Effects

readwrite

effects: read, write; idempotent

Options

  • --dry-runeffects become: read

    print what would be written and write nothing

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

  • --recipe <name>one of deps, factory, repo

    the way of working to write; read back from the block when omitted

  • --feedback

    also include recording documentation problems

  • --hooks

    add a SessionStart hook that keeps the index in step

  • --mcp

    add the MCP server to .mcp.json

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack agent install
$ docspack agent install --feedback --hooks
$ docspack agent install --recipe factory
$ docspack agent install --recipe repo

Build a command line

Inherited options

Use a different index

Run in a different directory

the way of working to write; read back from the block when omitted

sh
docspack agent install

docspack agent check

Fail when the wiring is missing or out of date

sh
docspack agent check [options]

Effects

read

effects: read; idempotent

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

  • --recipe <name>one of deps, factory, repo

    the way of working to write; read back from the block when omitted

  • --feedback

    also include recording documentation problems

  • --hooks

    add a SessionStart hook that keeps the index in step

  • --mcp

    add the MCP server to .mcp.json

Exit statuses

  • 0success
  • 1the wiring is missing or out of date
  • 2the command was used wrongly

Examples

sh
$ docspack agent check

Build a command line

Inherited options

Use a different index

Run in a different directory

the way of working to write; read back from the block when omitted

sh
docspack agent check

docspack changed

What a library's exports gained and lost between two versions

Compares two versions already in the global store, which is shared by every project on this machine, so nothing is fetched. Without a version it compares what is installed here against the most recently indexed other version.

Upgrades are overwhelmingly additive: the useful answer is what exists now that an older release did not have, and which of those names no documentation here mentions — the ones a model can know from neither its training data nor the vendor’s pages.

sh
docspack changed <library> [options]

Effects

read

effects: read; idempotent

Arguments

  • <library>required

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack changed hono
$ docspack changed hono@4.0.0

Build a command line

Inherited options

Use a different index

Run in a different directory

sh
docspack changed <library>

docspack verify

Check the docs still describe the code you installed

Compares the identifiers the chunks name against what the documented libraries declare, read from their .d.ts files. Nothing you depend on is imported or executed. The libraries come from the manifest’s “documents”, or from the docspack key when the manifest has none.

sh
docspack verify [options]

Effects

read

effects: read; idempotent

Options

  • --package-dir <d>directory

    verify one package directory instead of what is installed

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1anything was reported
  • 2the command was used wrongly

Examples

sh
$ docspack verify
$ docspack verify --json

Build a command line

verify one package directory instead of what is installed

Inherited options

Use a different index

Run in a different directory

sh
docspack verify

docspack feedback

Record documentation problems: add, list, submit, remove

Writes to .docspack/feedback.jsonl in this project. Nothing is transmitted: docspack contains no code that can send a report anywhere.

drift must name the identifier that drifted. incorrect and missing must carry —expected, —actual and —repro, so a claim that cannot show its work cannot be recorded. submit prints a prefilled GitHub issue URL for a human to open and file.

sh
docspack feedback <command> [options]

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Commands

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

docspack feedback add

Record one problem

sh
docspack feedback add [options]

Effects

write

effects: write

Options

  • --chunk <id>required

    the chunk the problem is in

  • --kind <k>one of drift, incorrect, missing; default drift
  • --evidence <text>required

    the claim, in one line

  • --expected <text>

    what the documentation led you to expect

  • --actual <text>

    what happened instead

  • --repro <code>

    code that demonstrates it

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Constraints

  • --kind=incorrect requires: --expected, --actual, --repro

  • --kind=missing requires: --expected, --actual, --repro

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack feedback add --chunk @acme/docspack@1.4.0/api-auth --kind drift --evidence "client.setKey is not exported; setApiKey is"

Build a command line

the chunk the problem is in

the claim, in one line

what the documentation led you to expect

what happened instead

code that demonstrates it

Inherited options

Use a different index

Run in a different directory

sh
docspack feedback add --chunk <id> --evidence <text>

docspack feedback list

Show recorded problems

sh
docspack feedback list [options]

Effects

read

effects: read; idempotent

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack feedback list

Build a command line

Inherited options

Use a different index

Run in a different directory

sh
docspack feedback list

docspack feedback submit

Print a prefilled GitHub issue URL for a human to open

sh
docspack feedback submit [options]

Effects

read

effects: read; idempotent

Options

  • -p, --package <s>

    only findings from packages matching this text

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack feedback submit

Build a command line

only findings from packages matching this text

Inherited options

Use a different index

Run in a different directory

sh
docspack feedback submit

docspack feedback remove

Delete recorded problems

sh
docspack feedback remove [<fingerprint>...] [options]

Effects

destructive

effects: destructive; idempotent

Arguments

  • [<fingerprint>...]

Options

  • --all

    every recorded finding

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Constraints

  • exactly one of: fingerprint, --all

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack feedback remove <fingerprint>

Build a command line

One per line.

Inherited options

Use a different index

Run in a different directory

sh
docspack feedback remove

docspack mcp

Serve the index over MCP instead, as a long-lived process

Serves the same index over the Model Context Protocol, for clients that prefer a tool definition to a shell command. query_local_docs returns exactly what ask prints. stdout is the protocol channel, so nothing else is written to it.

sh
docspack mcp [options]

Effects

read

effects: read; runs until stopped

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Input and output

  • stdin

    application/jsonl, MCP requests

  • stdout

    application/jsonl, MCP responses

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack mcp

Build a command line

Inherited options

Use a different index

Run in a different directory

sh
docspack mcp

docspack sources

List curated sources that `docspack build` can fetch

sh
docspack sources [options]

Effects

effects: none; idempotent

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack sources
$ docspack build hono --name @docspack-community/hono

Build a command line

Inherited options

Use a different index

Run in a different directory

sh
docspack sources

docspack init

Scaffold a documentation package, then build and check it

Reads the surrounding project first — name, version, a docs directory, an OpenAPI document, the git remote, the license — and proposes a package built from what it found.

sh
docspack init [<name>] [options]

Effects

readwritenetwork

effects: read, write, network; prompts on a terminal unless --yes

Arguments

  • [<name>]

    package name

Options

  • -y, --yes

    skip the prompts and use flags plus detected defaults

  • --dry-runeffects become: read

    print the file tree and write nothing

  • --mirror <id|url>

    bootstrap from a published llms.txt

  • --community

    scaffold under @docspack-community

  • --template <t>one of full, minimal; default full
  • --mode <m>one of standalone, in-repo
  • --workflowundone by --no-workflow

    write the release workflow (the default)

  • --buildundone by --no-build

    build and check after scaffolding (the default)

  • --name <name>

    package name, e.g. @acme/docspack

  • --pkg-version <v>

    package version

  • --from <dir>directory

    directory of Markdown to package

  • --openapi <file>file

    OpenAPI JSON to package

  • --out <dir>directory; default ./docspack

    where to scaffold

  • --force

    overwrite files that already exist

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack init
$ docspack init --name @acme/docspack --from ./docs --yes
$ docspack init --mirror hono --community --yes

Build a command line

bootstrap from a published llms.txt

write the release workflow (the default)

build and check after scaffolding (the default)

package name, e.g. @acme/docspack

package version

directory of Markdown to package

OpenAPI JSON to package

where to scaffold

Inherited options

Use a different index

Run in a different directory

sh
docspack init

docspack build

Generate the .llms/ payload for publishing

Splits each document at ## headings, then ###, then paragraphs, until every chunk fits the budget. —min-chunk-tokens packs the other way first, merging adjacent sections up to the budget: use it for generated reference, where a heading is a field name and one chunk per heading is hundreds of chunks too small to answer anything.

—openapi writes one chunk per operation: the base URL, the credential, the inputs with their types, the response, the failures and a runnable curl call, in LAPIS notation. Each chunk answers to both POST /v1/charges and the operationId, so docspack ask can be given either. Combine it with —from to publish prose and an API in one package.

—cmdspec writes one chunk per command of a command-line interface described in cmdspec, or in OpenCLI or Usage, converted: the synopsis, the inputs with their types and defaults, what the command changes, what it prints and what its exit status means. Each chunk answers to its command path, so docspack ask "git remote add" pins it.

With no flags, settings are read from the docspack key of the package.json in —out.

sh
docspack build [<source>] [options]

Effects

readwritenetwork

effects: read, write, network; idempotent

Arguments

  • [<source>]

    a curated source to fetch, from `docspack sources`

Options

  • --from <dir>directory

    directory of Markdown to package

  • --openapi <file>file

    OpenAPI 3 document (JSON or YAML), one chunk per operation

  • --cmdspec <file>file

    CLI description (cmdspec, OpenCLI or Usage), one chunk per command

  • --from-json <file>file; - means standard input or output

    JSON records to package, or `-` for standard input

  • --name <name>

    package name, e.g. @acme/docspack

  • --pkg-version <v>

    package version

  • --out <dir>directory; default the current directory

    output directory

  • --pages <n>integer; at least 1

    maximum documents to fetch from a remote source

  • --max-chunk-tokens <n>integer; at least 1; default 800

    split a section above this size

  • --min-chunk-tokens <n>integer; at least 1

    pack adjacent sections up to this size before splitting

  • --documents <p>repeatable

    library this package documents, such as acme@1.4.0

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Constraints

  • at most one of: source, --from

  • at most one of: source, --openapi

  • at most one of: source, --cmdspec

  • at most one of: source, --from-json

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack build

$ docspack build --from ./docs --name @acme/docspack --pkg-version 1.4.0

$ docspack build --from ./reference --min-chunk-tokens 400 --max-chunk-tokens 900

$ docspack build --openapi ./openapi.json

# Prose and an HTTP API in one package
$ docspack build --from ./docs --openapi ./openapi.json

$ docspack build --from ./docs --cmdspec ./cmdspec.yaml

Build a command line

directory of Markdown to package

OpenAPI 3 document (JSON or YAML), one chunk per operation

CLI description (cmdspec, OpenCLI or Usage), one chunk per command

JSON records to package, or `-` for standard input

package name, e.g. @acme/docspack

package version

output directory

maximum documents to fetch from a remote source

split a section above this size

pack adjacent sections up to this size before splitting

library this package documents, such as acme@1.4.0

Inherited options

Use a different index

Run in a different directory

sh
docspack build

docspack doctor

Check a package the way the indexer and a reviewer would

Errors are packages that will not index. Warnings are packages that will index and retrieve badly. Prose style is a note unless —pedantic, because writing by hand is not a reason to block a first publish.

sh
docspack doctor [options]

Effects

read

effects: read; idempotent

Options

  • --strict

    treat structural warnings as failures

  • --pedantic

    --strict, and fail on prose style as well

  • --package-dir <d>directory; default .

    the package to read

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1the package is not ready to publish
  • 2the command was used wrongly

Examples

sh
$ docspack doctor
$ docspack doctor --strict
$ docspack doctor --json

Build a command line

the package to read

Inherited options

Use a different index

Run in a different directory

sh
docspack doctor

docspack preview

Answer a query from the local package, as an agent would

Indexes the package in memory and answers through the same ranking and token budget an agent gets. Nothing is published, installed, or written to the global store.

sh
docspack preview <query>... [options]

Effects

read

effects: read; idempotent

Arguments

  • <query>...required

Options

  • --package-dir <d>directory; default .

    the package to read

  • --limit <n>integer; at least 1; default 3

    maximum chunks to return

  • --max-tokens <n>integer; at least 1; default 3000

    token ceiling for the result set

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1the command failed
  • 2the command was used wrongly

Examples

sh
$ docspack preview "how do I authenticate"

Build a command line

One per line.

the package to read

maximum chunks to return

token ceiling for the result set

Inherited options

Use a different index

Run in a different directory

sh
docspack preview <query>...

docspack eval

Measure retrieval against a set of questions

The evaluation set is a JSON array of questions and the chunk ids that would answer them:

plaintext
[{ "query": "how do I verify a webhook signature", "expect": "webhooks-signing" },
 { "query": "rate limits", "expect": ["rate-limits", "errors"] }]

Reports hit rate, top-1 rate and mean answer size — the numbers that settle the chunk budget, which no structural check can see. With —min-hit-rate it gates a publish on retrieval quality the way doctor --strict gates it on structure.

sh
docspack eval <queries> [options]

Effects

read

effects: read; idempotent

Arguments

  • <queries>requiredfile

Options

  • --package-dir <d>directory; default .

    the package to read

  • --limit <n>integer; at least 1; default 3

    chunks per answer, the window a hit must fall in

  • --max-tokens <n>integer; at least 1; default 3000

    token ceiling for each answer

  • --min-hit-rate <n>number; 0 to 100

    exit 1 below this percentage of questions answered

Inherited options

  • --store <path>file; default ~/.docspack/store.db; env DOCSPACK_STORE

    Use a different index

  • --cwd <dir>directory; default the current directory

    Run in a different directory

  • --json

    Machine-readable output

  • -q, --quiet

    Only print errors

  • -h, --help

    Show this help, or a command's help

Exit statuses

  • 0success
  • 1the hit rate is below --min-hit-rate
  • 2the command was used wrongly

Examples

sh
$ docspack eval ./eval/queries.json
$ docspack eval ./eval/queries.json --min-hit-rate 90
$ docspack eval ./eval/queries.json --limit 1 --json

Build a command line

the package to read

chunks per answer, the window a hit must fall in

token ceiling for each answer

exit 1 below this percentage of questions answered

Inherited options

Use a different index

Run in a different directory

sh
docspack eval <queries>

Generated from cmdspec.json by @docspack/sheaf-react. Each command's builder writes a command line to copy; it runs nothing.

The same ranking docspack search uses, over the same 15 documents.