Docs · CLI reference

CLI reference

The ts-capture CLI ships with @ts-capture/core. Run ts-capture --help for this summary. Commands below are listed in roughly the order of a typical observe → merge → apply run.

Commands marked ✏️ write to your source files. Run them from a committed working tree — see Review & apply safely.

ts-capture instrument <file> [--in-place] ✏️ #

Instrument a single file with type tracking. The output carries ts-capture's runtime hooks: run it, then discard it — never commit or deploy instrumented code.

ts-capture merge <dir-or-files...> [--out <path>] #

Merge per-process ts-capture-types-*.json dumps into one types.json. Vitest's forks pool emits one dump per spec, so merge before apply.

ts-capture apply <types.json> [--dry-run] [--comments|--both] [--include-tests] [--force] [--report] [--telemetry] [--project <tsconfig.json>] ✏️ #

Apply collected types to source files. Editing those files between collection and apply invalidates the recorded offsets, and the output is not formatted — see Review & apply safely.

Flags apply does not know are reported on stderr and the run continues without them, naming the nearest known flag: --comment is not --comments, and the difference is a preview against a rewrite.

Every run says how much it wrote, and whether any observation went unused:

Current
apply: 47 annotations written in 6 files.
       12 observed positions not written (6 would add a type error, 6 with no type information) - see --report.

--report adds one entry per unused observation. An annotation that would introduce a type error anywhere in the project is never written, test files included, and the entry names the error:

Input
// src/cart.ts — observed with { lines: [...] }
export function addLine(cart, product, quantity) {
  cart.lines.push({ sku: product.sku, quantity, unitPrice: product.price });
  return cart;
}

// src/pricing.spec.ts — adds a property the observed shape does not have
const cart = addLine(createCart(), chair, 2);
cart.coupon = { kind: "percent", value: 50 };
Current
Observed but not written (12)

  Would add a type error (6)
    src/cart.ts:5:25  cart
      observed  { lines: unknown[] } | { lines: { quantity: number, sku: string, unitPrice: number }[] }
      TS2339 at src/pricing.spec.ts:22: Property 'coupon' does not exist on type '{ lines: { quantity: number; sku: string; unitPrice: number; }[]; }'.

  Carries no type information (6)
    src/orders.ts:10:15  gateway
      observed  { calls: unknown[], charge(amount: unknown, reference: unknown): Promise<unknown> }

Nothing to add (16)
  16 already inferred by TypeScript

The groups are: would add a type error, carries no type information (an empty array, unknown, a function whose parameters were never observed), refers to a type this file cannot name, and falls outside the type already there — the type TypeScript infers at that position, which the run contradicts. Positions where TypeScript already infers the same type, or that already have a written type, are counted under Nothing to add and not listed. Apply is never given an observation of a type you wrote, so already annotated counts positions typed since the run, mostly by an earlier apply.

ts-capture coverage <tsconfig.json> #

Report the type-coverage percentage for a project.

ts-capture verify <types.json> --project <tsconfig.json> [--threshold=N] #

Compare runtime observations with the type at each observed position, and rewrite nothing. By default only positions without a type are instrumented, so the type compared against is what TypeScript infers there: a parameter's contextual type, a variable's initializer type, a function's inferred return type.

Run the tests with TS_CAPTURE_OBSERVE_ANNOTATED=1 and parameters and return types you wrote are observed too, and compared with what you wrote (what is checked).

Every mismatch is printed with its location, then one line of totals and the reasons for any unverifiable position. A run with no mismatch, from a small cart module:

Current
9 observed positions: 8 match, 0 mismatch, 1 unverifiable, 0 without a declaration.
  unverifiable: 1 declared any

When written types were observed, they get a section of their own, ahead of the inferred ones:

Current
Written types (21 checked)
src/cart.ts:17:52  qty
  declared  string
  observed  number
  18 match, 1 mismatch, 2 unverifiable, 0 without a declaration.
  unverifiable: 1 literal declared type, 1 declared any

Inferred types (9 checked)
  8 match, 0 mismatch, 1 unverifiable, 0 without a declaration.
  unverifiable: 1 declared any

When none were, verify says so on stderr, so a run without the variable does not read as "every type you wrote is right".

TypeScript does the comparing: each observed type is resolved in the file it was seen in, a name the file does not import through the one module that exports it, and checked for assignability to the type at the position. A position is unverifiable when the run cannot decide: the type is any, unknown, polymorphic this or generic; it is a literal type the run widens ("a" is observed as string) or narrower than any observation can show (a brand, type arguments); a name in the observation is in no module, or in more than one; or the type requires what the runtime does not record (symbol keys, methods a class instance inherits). An observed undefined matches a void return. An async return is compared with what its promise resolved to; one whose promise never settled is unverifiable. Without a declaration counts positions whose file is not in the project, or that no longer line up with a declaration because the source changed after observation.

ts-capture instrument-bundle <bundle.js> [--out <path>] #

Instrument an already-bundled JS artefact (for the bundle-observation flow). The result is for observation only — never ship it.

ts-capture apply-bundle <observations.json> --map <bundle.js.map> [--bundle <bundle.js>] ✏️ #

Translate observations collected from a bundle back to source positions via the source map, then apply.

ts-capture --help #

Show the usage summary.

For configuration flags (infer.*, apply.*) — set in ts-capture.config.json or via --infer.<path>=<value> — see the configuration reference.