@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.