Twilic CLI

Command-line tool for encoding JSON to Twilic, decoding Twilic to JSON, and benchmarking against other binary formats.

Package: @twilic/cli
Source: github.com/twilic/cli

Install

pnpm add -g @twilic/cli @twilic/core

Or run without installing:

pnpx @twilic/cli encode --help

Requires @twilic/core as a runtime dependency for the encode/decode backend.

---

encode

Encode JSON to Twilic binary format.

# From stdin
echo '{"hello":"world","n":42}' | twilic encode

# From file
twilic encode -i data.json -o data.twilic

# Hex output (debugging)
echo '{"hello":"world"}' | twilic encode --hex

Options

Flag	Description
-i, --input <file>	Input JSON file (default: stdin)
-o, --output <file>	Output file (default: stdout)
--hex	Output hex string instead of raw binary

Examples

# Roundtrip test
echo '{"users":[{"id":1,"name":"alice"}]}' | twilic encode | twilic decode --pretty

# Encode fixture for interop test
twilic encode -i fixture.json -o fixture.twilic

---

decode

Decode Twilic binary to JSON.

# From stdin
cat data.twilic | twilic decode

# Pretty-print
twilic decode -i data.twilic --pretty

# From hex string (when piping --hex output)
echo "a1..." | twilic decode

Options

Flag	Description
-i, --input <file>	Input binary file (default: stdin)
-o, --output <file>	Output file (default: stdout)
--pretty	Pretty-print JSON output

BigInt serialization

Twilic encodes integers as 64-bit values. The CLI serializes decoded bigint values as JSON strings to preserve precision:

{ "id": "9007199254740993" }

---

bench

Benchmark Twilic encoding and decoding against MessagePack, CBOR, BSON, and JSON.

# Default benchmark
twilic bench

# WASM backend, longer run
twilic bench --backend wasm --time-ms 2000

# Save results as Markdown
twilic bench --markdown-out results.md

Options

Flag	Description
--backend <napi|wasm>	Backend (default: napi)
--time-ms <ms>	Time per task in ms (default: 1000)
--warmup-ms <ms>	Warmup time in ms (default: 250)
--markdown-out <file>	Append results as Markdown

Benchmark modes

The benchmark repository supports additional modes not exposed in the CLI wrapper:

• Single-record encode/decode
• Batch encode (256 records)
• Transport-JSON fast path
• Stateful patch simulation

See Performance guide and Benchmark page.

---

Scripting patterns

CI size regression

#!/bin/bash
SIZE=$(echo "$FIXTURE" | twilic encode | wc -c)
if [ "$SIZE" -gt "$MAX_BYTES" ]; then
  echo "Payload too large: $SIZE > $MAX_BYTES"
  exit 1
fi

Inspect production payload

curl -s -H "Accept: application/vnd.twilic" https://internal/api/users \
  | twilic decode --pretty \
  | jq '.[0]'

Generate test fixtures

twilic encode -i tests/fixtures/users.json -o tests/fixtures/users.twilic
git add tests/fixtures/users.twilic

---

Exit codes

Code	Meaning
0	Success
1	Invalid input, decode error, or I/O failure

---

Related

• JavaScript Core API
• Troubleshooting
• Playground