@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
• Agreement execution: agreement prepare/inspect/approve/countersign/status/signing-copy/executed-copy/evidence/revise/rejected/withdrawn/recover
• 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.

Engagement letters now start unsigned. Register your client contact separately from yourself, then prepare the client signing copy. A client's CEO or CFO title belongs in --title; use --role counterparty for their part in this agreement.

npx klevar-docs signers add DOCUMENT_ID --name "Client contact" --email "[email protected]" --role counterparty --title "CEO" --json
npx klevar-docs agreement prepare DOCUMENT_ID --company-name "Kingsley Onoh" --json
npx klevar-docs agreement signing-copy DOCUMENT_ID --out unsigned.pdf
npx klevar-docs signed-copy upload DOCUMENT_ID --file client-return.pdf --signer-id SIGNER_ID --source email --json
npx klevar-docs agreement inspect DOCUMENT_ID --copy-id COPY_ID --json
npx klevar-docs agreement approve DOCUMENT_ID --file approval.json --json
npx klevar-docs agreement countersign DOCUMENT_ID --approval-id APPROVAL_ID --json
npx klevar-docs agreement executed-copy DOCUMENT_ID --out executed.pdf
npx klevar-docs agreement evidence DOCUMENT_ID --out evidence.zip

Upload alone does not mark the agreement signed. Read the returned PDF, check every client contact's authority and record your terms decision in approval.json. Approval binds the exact PDF hash and your signature asset. Digital countersigning also binds the company certificate. A scan needs explicit page coordinates for your image. See the signing guide for the approval JSON, revisions, recovery and evidence limits.

These commands do not send client email. Send the downloaded signing copy and finished PDF yourself. signed-copy get retrieves a client return; agreement executed-copy retrieves the completed agreement. Old records are labelled legacy_not_assessed.

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.