Guide

CLI

encode and decode and identify and convert and list from the terminal. Bytes go to stdout raw and everything else goes to stderr

Install or run once

shell
pnpm add -g @agntn/encodings
npx @agntn/encodings identify 'JBSWY3DPEBLW64TMMQ======'

Commands

CommandDoes
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, or --peel them off layer by layer
encodings convert <input> --from <page>Read text as bytes in one code page and write them in another
encodings list [encoding]Every encoding, one family with --family, or one with its alphabet and options
encodings mcpThe 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.

Text that starts with -? Ascii85, Z85 and the URL alphabet of base64 all write one. Just type it. A dashed word counts as an option only when it spells one, so the rest is text:

shell
encodings decode base85 --alphabet ascii85 -Y7,
# 'em

A typo still fails, though. --outptu hex names no option, and the error lists the ones decode does take. Text that does spell a flag, like -o itself, goes after --.

Stdout is the answer

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

shell
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

shell
encodings encode hex --input-format base64 aGk=
# 6869

encodings encode base58 0062e907b15cbf27d5425399ebf6f0fb50ebb88f18 --input-format hex --check
# 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.

shell
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. --alphabet, --check, --blocks, --m, binary's --symbols, --bits and --order, and base256's --symbols, --sample and --multibase change how the text reads, so decode takes them too. --canonical on base32 and base64 is decode only, since it just checks the spare bits of the last character:

shell
encodings decode base32 CPNMUOJ1E8 --alphabet hex
# foobar

Identify

shell
encodings identify 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa -n 2
# 1. base58 (check) 0.574; checksum matches
#    21 bytes, hex 0062e907b15cbf27d5425399ebf6f0fb50ebb88f18
# 2. base32 (alphabet=crockford) 0.043
#    21 bytes, hex 0a83fb05d62de0e7844da5b4fd04b90d3676876faa

The same text an agent gets from encodings_identify, word for word. Encoding, score and reasons, then the decoded bytes as text or hex. -n sets how many. A candidate that needed an option names it in brackets: (check) is --check for decode, (alphabet=crockford) is --alphabet crockford.

Two layers deep? --peel goes down, outermost first.

shell
encodings identify --peel 5958523059574e7249474630494752686432343d
# 2 layers, outermost first:
# 1. hex 0.414; decodes to readable text, fits a 16-character alphabet
#    20 bytes, text "YXR0YWNrIGF0IGRhd24="
# 2. base64 0.571; padding fits the block length, decodes to readable text
#    14 bytes, text "attack at dawn"

Here -n caps the layers, ten by default. A last layer marked unconfirmed guess is only that, a guess.

Want data, not prose? identify and list take --json and print the details as JSON. Good for jq, bad for reading at 2am.

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.

shell
encodings decode base58 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNb --check
# base58: checksum does not match
echo $?
# 1

No colors, anywhere. A pipe, a file and an agent's transcript all get the same plain text your terminal does.