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, 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 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.
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:
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
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 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.
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:
encodings decode base32 CPNMUOJ1E8 --alphabet hex
# foobar
Identify
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.
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.
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.