Data tooling

Projection and conversion flags

Format projection is a top-level flag surface, not a subcommand. One flag picks the output projection of an input document; --from / --to drive explicit conversions:

      $ cx --ast config.cx                 # JSON AST
         $ cx --json config.cx                # JSON projection
         $ cx --yaml config.cx                # YAML projection
         $ cx --xml --compact config.cx       # XML, minimised
         $ cx --from=md --to=cx README.md     # Markdown in, CX out
         $ cx --from=cx --to=json --lossless order.cx
         $ echo '[hello world]' | cx --json -  # stdin
    

• Projection flags: --ast --cx --xml --json --yaml --toml --md --csv --tsv --psv, each optionally with --compact.
• --from=cx|xml|json|yaml|toml|md|csv|tsv|psv --to=cx|xml|json|yaml|toml|md|csv|tsv|psv — explicit conversion; --lossless makes XML carry per-value types (<cx:T>) for an exact round-trip.
• --include-root=DIR — resolve [?cx include=…] against DIR before projecting (include resolution is opt-in; without a root the directive is preserved).

cx fmt

Pretty-prints in lossless canonical form. Comments, anchors, and authorial structure are preserved; whitespace and quoting are normalised. Reads the file argument (or stdin) and writes the formatted document to stdout.

      $ cx fmt config.cx                    # formatted, to stdout
         $ cx fmt config.cx > config.fmt.cx && mv config.fmt.cx config.cx
    

cx canonical / cx hash / cx eq

cx canonical emits the strict canonical text per spec/core/canonical.md: comments stripped, attributes sorted, anchors expanded, whitespace collapsed, quoting normalised. Two data-equivalent inputs produce identical output — that is the contract cx hash (SHA-256 of those bytes) and cx eq (exit 0 iff the strict-canonical forms match, 1 if they differ, 2 on error) build on.

      $ cx canonical config.cx | shasum -a 256   # equivalent to cx hash
         $ cx hash config.cx
         $ cx eq prod.cx proposed.cx && echo unchanged || echo changed
    

cx validate

Validates a document against a .cxs schema (spec/core/schema.md). Flags: --schema=SCHEMA.cxs (required), --fail-on=info|warn|error|none (default error), --mode=open|strict|closed (overrides the schema-mode directive), --apply-defaults (materialise schema-default attribute values). Exit 0 if no diagnostics at/above the threshold, 1 if any, 2 on I/O or schema failure.

      $ cx validate users.cx --schema=users.cxs
         $ cx validate users.cx --schema=users.cxs --mode=strict --fail-on=warn
    

cx select

CXPath query over one document — cx select 'PATH' [FILE] (stdin when FILE is - or absent). The document binds as $doc; PATH is a single CXPath value expression ($doc/…, /…, or //…, predicates included). Matches print one per line in canonical CX, in document order; attribute-axis matches materialize as [name value] fields. Exit 0 with at least one match, 1 on an empty match set (grep-style), 2 on error. A pure read — no capability grants accepted or needed. Contract: spec/misc/cli.md §3.8.

      $ cx select '//user[= $_@role admin]' users.cx
         [user name=Alice role=admin]
         $ cx select '$doc/user@name' users.cx
         [name 'Alice']
         [name 'Bob']
         $ cat users.cx | cx select '//user' && echo matched
    

cx table

The public Table API surface for CXCol / [table[…]] payloads: cx table info FILE (column/row counts, types, byte size), cx table dump FILE --to=cx (round-trip via the Table API), cx table load FILE --to=cx (symmetric inverse). Parquet / Arrow output (--to=parquet|arrow) defers to the libcx_arrow bridge. See analytics.

      $ cx table info data.cxbin
         $ cx table dump data.cxbin --to=cx | head
    

cx diff

Semantic diff — walks the strict-canonical forms, so presentation-only edits produce no delta. See diff for the output contract. Flags: --format=unified|json|summary (default unified), --no-color. Exit codes match diff(1): 0 equal, 1 differs, 2 error.

      $ cx diff prod.cx proposed.cx
         $ cx diff --format=json prod.cx proposed.cx
         $ cx diff prod.cx proposed.cx && echo no-op   # CI gate
    

Diff semantics

cx diff produces a semantic diff — tree-structured, canonical-byte-aware, formatting-blind. Two data-equivalent inputs diff to nothing, even if they differ at the text level. This is what makes cx diff usable as a CI gate: it reports semantic deltas, not formatting noise.

        $ cx diff prod.cx proposed.cx
           --- prod.cx
           +++ proposed.cx
           @@ /config/database @@
            host='primary.db'
           -port=5432
           +port=5433
            replica='secondary.db'
      

        [
             {
               \"kind\": \"attribute-changed\",
               \"path\": \"/config/database/@port\",
               \"before\": {\"name\": \"port\", \"value\": 5432, \"type\": \"int\"},
               \"after\":  {\"name\": \"port\", \"value\": 5433, \"type\": \"int\"}
             }
           ]
      

        *.cx    diff=cx
           *.cxd   diff=cx
           *.cxs   diff=cx
      

        # One-time per repo
           git config diff.cx.command 'cx diff'
      

        # Use directly as a CI gate
           cx diff prod.cx proposed.cx && echo no-change || review-changes