CLI
Install or run once
pnpm add -g @agntn/encodings
npx @agntn/encodings identify 'JBSWY3DPEBLW64TMMQ======'
Commands
| Command | Does |
|---|---|
encodings encode <encoding> <input> | Write text or bytes in an encoding |
encodings decode <encoding> <text> | Read it back into bytes |
encodings identify <text> | Rank the encodings it decodes in |
encodings list [encoding] | Every encoding, one family with --family, or one with its alphabet and options |
encodings mcp | The MCP server over stdio |
- instead of the input reads stdin. encode takes it byte for byte. decode and identify drop one trailing line break, the one your shell pipe added.
Stdout is the answer
encodings encode base64 'hello world!'
# aGVsbG8gd29ybGQh
encodings decode base64 aGVsbG8gd29ybGQh
# hello world!
decode writes the raw bytes, like base64 -d does. Pipe them into a file, into xxd, into the next command. Binary in your terminal? Add -o hex or -o base64.
Whatever the text carried besides data goes to stderr. One key: value per line. Stdout stays clean.
encodings decode bech32 bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4 -o hex
# prefix: bc (stderr)
# witnessVersion: 0 (stderr)
# 751e76e8199196d454941c45d1b3a323f1433bd6
Those values come from the text, so they're escaped before they reach your terminal. A uuencode file name with an escape sequence shows up as \u001b. Not as a recolored prompt.
Bytes in
encodings encode hex --input-format base64 aGk=
# 6869
encodings encode base58check 0062e907b15cbf27d5425399ebf6f0fb50ebb88f18 --input-format hex
# 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
--input-format is utf8 by default. hex and base64 encode the bytes they spell.
Options
A flag only reaches the encodings that declare it. Anything else is an error.
encodings encode bech32 gm --prefix test
# test1vaks69jerm
encodings encode base64 gm --prefix bc
# Invalid option prefix=bc: base64 does not take it
Not sure what one takes? encodings list <encoding> shows it.
Identify
encodings identify 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa -n 2
# 0.574 base58check 0062e907b15cbf27d5425399ebf6f0fb50ebb88f18 (checksum matches)
# 0.043 base32-crockford 0a83fb05d62de0e7844da5b4fd04b90d3676876faa
Score, encoding, the decoded value as text or hex, and the reasons. -n sets how many.
Exit codes
0 when it worked. 1 with one line on stderr when it didn't. A bad character, a checksum that doesn't match, an unknown encoding. Or identify finding nothing at all.
encodings decode base58check 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNb
# base58check: checksum does not match
echo $?
# 1
Colors only when both stdout and stderr are a terminal that takes them. A pipe gets plain text.