Guides

Task-oriented recipes for the cosyte command. Each is a short, copy-pasteable answer to one real question.

Status: pre-alpha (0.0.x), published to npm at 0.0.1. That release cannot be installed (a packaging defect: see Installation), so run the CLI from a source checkout for now. The cosyte command wraps all eight cosyte formats (HL7 v2, FHIR R4, X12, ASTM, NCPDP SCRIPT, C-CDA, DICOM, MLLP) plus the @cosyte/transform and @cosyte/terminology higher-layer libraries: parse (autodetect → typed JSON, with NDJSON streaming for MLLP frames and --ndjson), validate (verdict in the exit code), inspect (a value-free structural summary), fmt (canonical re-serialization), convert (HL7 v2 → FHIR R4 via @cosyte/transform), map-codes (ConceptMap $translate via @cosyte/terminology), redact/deid (an honest gated stub, exit 69, until the CLI wires @cosyte/deid), and completion (a shell completion script). Support is honest per (format, operation): a parser that does not faithfully support a command (DICOM parse/fmt, C-CDA parse, MLLP fmt/validate) is a value-free CLI_FORMAT_UNSUPPORTED, never a fake. PHI discipline runs throughout: value-free by default, the opt-in --unsafe-show-values, never a PHI temp file. A cosyte-mcp MCP server exposes the same core to an LLM/agent. A command is only documented here once its behavior ships and its example passes the doc/code-agreement check.

Parse from a pipeline and select a field

parse is pipeline-first. Use --json for compact output and pipe it to jq:

cat adt.hl7 | cosyte parse - --json | jq '.model.segments[0]'

Branch on the outcome in CI

The exit code is the contract, no need to grep stdout:

if cosyte parse "$file" > /dev/null 2> err.log; then
  echo "parsed OK"
else
  code=$?   # 65 = unparseable/undetected, 66 = missing file, 2 = usage
  echo "parse failed with exit $code"; cat err.log   # err.log is value-free
fi

Force a format when autodetection can't

A .txt that is really HL7, or an ambiguous input, takes an explicit --format:

cosyte parse --format hl7 weird-extension.txt

Debug a rejected message (and mind the PHI)

A CLI_PARSE_FAILED line is value-free by default: a code and position, never the bytes. When you are working locally and need to see what the parser choked on, add the loud, opt-in --unsafe-show-values (it is PHI-exposing, never on stderr you will share):

cosyte parse broken.hl7 --format hl7                       # value-free diagnostic
cosyte parse broken.hl7 --format hl7 --unsafe-show-values  # appends a bounded input excerpt

Convert an HL7 v2 feed to FHIR in a pipeline

convert wraps @cosyte/transform: the FHIR Bundle is on stdout, the value-free conversion issues on stderr, and an error-severity issue sets a non-zero exit:

cat adt.hl7 | cosyte convert - --to fhir | jq '.entry[].resource.resourceType'

Translate a code through a bring-your-own ConceptMap

map-codes wraps @cosyte/terminology. A code and a ConceptMap are reference data (not PHI), so the target coding lands on stdout; an unmapped code is a value-free signal and a non-zero exit:

cosyte map-codes gender.conceptmap.json \
  --system http://hl7.org/fhir/administrative-gender --code male --json

Use the programmatic core

The same autodetection and exit-code contract are importable, useful when embedding the routing logic:

import { detectFormat, EXIT } from "@cosyte/cli";

const enc = new TextEncoder();
const detected = detectFormat(enc.encode('{"resourceType":"Bundle"}'));
detected.format; // => "fhir"
detected.confidence; // => "certain"
EXIT.USAGE; // => 2

Until more commands ship, the Quickstart covers the one-line parse and the API Reference documents every export.