@twilic/cli

CLI tool for encoding, decoding, and benchmarking Twilic binary data.

Install

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

Or run without installing:

pnpx @twilic/cli encode --help

Commands

encode

Encode JSON to Twilic binary format.

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

# From file, output to file
twilic encode -i data.json -o data.twilic

# Hex output (debug)
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 as hex string instead of raw binary |

decode

Decode Twilic binary format to JSON.

# From stdin
cat data.twilic | twilic decode

# From file, pretty-print
twilic decode -i data.twilic --pretty

# Roundtrip
echo '{"hello":"world"}' | twilic encode | twilic decode --pretty

Options:

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

Note: Twilic encodes integers as 64-bit values (u64/i64), which are decoded as JavaScript bigint. The CLI serializes bigint values as strings to preserve precision.

bench

Benchmark Twilic encoding and decoding against msgpack, cbor, bson, and JSON.

# Default benchmark
twilic bench

# Specify backend and duration
twilic bench --backend wasm --time-ms 2000

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

Options:

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

Changelog

See docs/CHANGELOG.md.

Publish to npm

The package ships build artifacts from dist/.

Local dry run:

pnpm build
pnpm pack

GitHub Actions publish uses npm trusted publishing (OIDC)—no long-lived NPM_TOKEN secret.

One-time setup on npmjs.com: open the package → Settings → Trusted Publisher → GitHub Actions, then set Organization or user twilic, Repository cli, and Workflow filename publish-npm.yml (exact name, including .yml). See also GitHub Actions OIDC.

Release steps:

1. Update docs/CHANGELOG.md and bump version in package.json.
2. Create and push matching tag v<version>.

Example:

git tag v0.1.0
git push origin v0.1.0

The workflow .github/workflows/publish-npm.yml verifies tag/version match, builds, and then runs npm publish (OIDC authentication via id-token: write).

Contributing

See docs/CONTRIBUTING.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.