Installation

@cosyte/cli ships the cosyte command as a Node.js executable, alongside cosyte-mcp. A global install is the simplest route; npx works too, with one flag noted under Run it.

Status: 0.1, published to npm, and the install commands below are live. While the package is below 1.0, a breaking change ships in a minor version and is called out in the changelog. 0.0.1 and 0.0.2 are on npm and cannot be installed: see If you are on 0.0.1 or 0.0.2. Every later version installs.

If you are on 0.0.1 or 0.0.2

Both are on npm, and npm install @cosyte/cli fails on either with an ENOENT:

npm error code ENOENT
npm error path node_modules/@cosyte/cli/vendor/cosyte-fhir-0.0.0.tgz
npm error enoent ENOENT: no such file or directory

npx and npm install -g fail identically. There is no consumer-side workaround, and nothing is wrong with your environment.

Those manifests declared the ten @cosyte/* sibling packages as local file paths (file:vendor/*.tgz) instead of npm version ranges. The tarballs are not part of the published package, so npm resolved the paths against a directory that is not there. A published version is immutable, so both stay broken. Every later version installs: npm install -g @cosyte/cli installs the current one.

What a default install includes

The siblings the CLI wraps are real npm ranges. HL7 v2 (@cosyte/hl7) and map-codes (@cosyte/terminology) run on the two hard dependencies. The six breadth formats X12, C-CDA, DICOM, NCPDP, ASTM, and MLLP, FHIR (@cosyte/fhir), @cosyte/transform, @cosyte/deid, and the MCP SDK (@modelcontextprotocol/sdk) are optional dependencies, so a default install has every one of them, whether it is npm install, pnpm add, or npm install --legacy-peer-deps.

An install with --omit=optional leaves all of them out. It still works for HL7 v2 and map-codes, and the commands that need a missing library report CLI_PARSER_UNAVAILABLE, naming the package to install, and exit 69; cosyte-mcp and cosyte mcp do the same without the MCP SDK. They do not guess, and they do not fail as though your input were bad.

Prerequisites

• Node.js 22 or later, tested on 22, 24, and 26 (the whole @cosyte/* suite targets ES2023). We claim only the release lines our CI runs: those three are tested on every change, and a later line is one nobody has exercised here yet.
• A package manager: pnpm, npm, or yarn.

Run it

Install globally to put cosyte on your PATH:

npm install -g @cosyte/cli
cosyte --help

Or run it without installing, naming the executable explicitly:

npx --package @cosyte/cli cosyte parse message.hl7

The short form npx @cosyte/cli … does not work, and it is a separate matter from the packaging defect above: it fails with could not determine executable to run. When a package ships more than one executable, npx runs the one whose name matches the package name's last segment, which would be cli; this package ships cosyte and cosyte-mcp. Use --package as above. A cli alias is deliberately not added, because npm install -g would then claim a command called cli on your PATH.

Programmatic API

The same core the CLI uses is available as a small library (the . subpath): the format autodetector, the exit-code contract, and the value-free diagnostic types:

import { VERSION } from "@cosyte/cli";

VERSION; // => "0.1.7"

If that resolves and prints the release you installed, the install is good: head to the Quickstart.

VERSION was wrong in 0.0.1 and 0.0.2. Both shipped exporting 0.0.0, and cosyte --version printed that too. This page asserted only typeof VERSION back then, which is true of every wrong value, so it stayed green across both. The constant is now kept in lockstep with the manifest by the release tooling and compared against it in the test suite, and the literal above is rewritten by that same step. A published version is never re-published, so those two copies stay wrong on the registry; if you have one, read the manifest instead, which was always correct: node -p "require('@cosyte/cli/package.json').version".