@klevar/docs-cli

Brain CLI wrapper for the Klevar Docs API. Production endpoint coverage is enforced by the source repo CLI coverage gate, with a digest snapshot for daily ops surfacing.

Install

npm install @klevar/docs-cli

Configure

Create ~/.klevar/docs.env (or set env vars):

DOCS_API_KEY=<your-bearer-token>
DOCS_API_URL=https://docs.klevar.ai

Or pass per-invocation:

npx klevar-docs --api-key=<token> --api-url=https://docs.klevar.ai invoice list

Usage

npx klevar-docs version
npx klevar-docs ping
npx klevar-docs invoice list
npx klevar-docs invoice create --client <client-id> \
  --line "Retainer:1500" --currency EUR --due 2026-06-30
npx klevar-docs invoice create --client <client-id> \
  --line "Retainer:1500" --currency EUR \
  --issue 2026-06-01 --due 2026-06-30 --send --json
npx klevar-docs invoice send INV-LLC-2026-0002 --json
npx klevar-docs invoice trail INV-LLC-2026-0002 --json
npx klevar-docs engagement-letter create --client "inselvolt GmbH" \
  --effective-date 2026-06-01 --tier builder_budget \
  --scope-summary "Billbee technical pivot" --body-file ./body.md \
  --fee-summary "USD 2,000/month capped rollover" --currency USD \
  --signatory-name "Kingsley Onoh" --visibility client --json
npx klevar-docs documents get <document-id> --out engagement-letter.pdf
npx klevar-docs reports revenue --entity llc --year 2026
npx klevar-docs hash-chain verify --entity <id>
npx klevar-docs admin events --limit 10

--help lists every command group. Use npx klevar-docs <group> --help and npx klevar-docs <group> <subcommand> --help for accurate subcommands and flags.

Help/documentation discipline:

• Treat tools/help-registry.ts plus the per-command handlers in tools/commands/ as the source of truth for user-facing flags.
• Do not document a flag until the handler parser/request-building path supports it and a CLI regression or coverage check pins it.
• Mark deferred or engine-owned behavior as a stub in command help and keep _stubs.ts aligned with coverage-gate expectations.

Output modes:

• default — human-readable
• --json — machine-parseable
• --quiet — IDs only, for shell pipelines

Invoice send responses include a delivery object for async Notification Hub outbox acceptance. invoice trail includes invoice_send_events alongside payment/receipt data for operator delivery follow-up.

Programmatic

import { createClient } from '@klevar/docs-cli';
import { checkDocs } from '@klevar/docs-cli/digest';
import { loadConfig } from '@klevar/docs-cli/config';

const config = loadConfig();
const client = createClient(config);
const digest = await checkDocs({ client });
console.log(digest.overdue_invoice_count);

What it covers

29 command modules covering every PRD §12 surface:

• Lifecycle: invoice / pro-forma / credit-note / payment / storno
• AP: vendor / vendor-bill / vendor-payment / vendor-credit-note / intercompany
• Pipeline: documents / templates / signatures / signing-cert / hash-chain / factur-x / xrechnung / signers
• Client documents: engagement-letter / letter / proposal / documents compose
• Signed copies: signed-copy upload/list/status/get/verify/supersede
• Operations: entity / clients / recurring / resolutions / reports / webhooks / email / audit / admin
• Reconciliation: reconcile / bulk

Deferred or engine-owned commands are labelled as stubs in command help and in the source repo's tools/commands/_stubs.ts allowlist.

Engagement-letter workflow

Use engagement-letter create for operator-friendly engagement letters. It builds the same payload as the advanced documents compose --type engagement_letter --body body.json path, then downloads with documents get <id> --out file.pdf for Brain/Gmail attachment.

After a client returns a signed PDF, store it as a first-class signed copy:

npx klevar-docs signed-copy upload <documentId> --file .\signed.pdf `
  --signer-email "[email protected]" --signer-name "Mathias Schick" `
  --signed-at 2026-05-19 --source email --notes "Returned by email" --json

npx klevar-docs signed-copy status <documentId> --json
npx klevar-docs signed-copy get <documentId> <signedCopyId> --out .\executed.pdf

signed-copy commands do not send client email. Invoice only after signature_status is fully_signed.

Operational discipline: create and send the engagement letter first; issue the invoice only after signed or clearly confirmed acceptance, unless the separate incident path is explicitly chosen.

CI guarantee

The source repo (klevar-docs) runs scripts/check-cli-coverage.ts on every PR — fails CI if any production endpoint lacks a CLI command, if a CLI references a path absent from the OpenAPI spec, or if a CLI body literal drifts from the OpenAPI requestBody schema (B148 schema-shape diff). Means this package's coverage tracks the API drift-free.

Releasing

Maintainer flow (B148 E3):

# From repo root, on a clean working tree:
./tools/scripts/release.sh patch    # bump 0.1.1 → 0.1.2
# or release.ps1 patch on Windows

Behind the scenes:

1. npm --tag-version-prefix=cli-v version <kind> in tools/ bumps tools/package.json, commits, and tags cli-v<new-version>.
2. git push origin --tags pushes the new tag.
3. .github/workflows/publish-cli.yml fires on the cli-v*.*.* tag, validates the tag matches tools/package.json, builds, and runs npm publish --access public.

Required repo secret: NPM_TOKEN (an Automation token from npmjs.org → Access Tokens). Set once via gh secret set NPM_TOKEN or the GitHub web UI.

Manual fallback: trigger the Publish @klevar/docs-cli to npm workflow from the Actions tab and supply the tag name as input.

License

UNLICENSED — internal Klevar Group tooling.