---
title: "CLI"
description: "encode and decode and identify and convert and list from the terminal. Bytes go to stdout raw and everything else goes to stderr"
canonical_url: "https://encodings.agntn.dev/guide/cli"
---
# 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

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

## Commands

<table>
<thead>
  <tr>
    <th>
      Command
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        encodings encode <encoding> <input>
      </code>
    </td>
    
    <td>
      Write text or bytes in an encoding
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        encodings decode <encoding> <text>
      </code>
    </td>
    
    <td>
      Read it back into bytes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        encodings identify <text>
      </code>
    </td>
    
    <td>
      Rank the encodings it decodes in, or <code>
        --peel
      </code>
      
       them off layer by layer
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        encodings convert <input> --from <page>
      </code>
    </td>
    
    <td>
      Read text as bytes in one <a href="https://encodings.agntn.dev/guide/code-pages">
        code page
      </a>
      
       and write them in another
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        encodings list [encoding]
      </code>
    </td>
    
    <td>
      Every encoding, one family with <code>
        --family
      </code>
      
      , or one with its alphabet and options
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        encodings mcp
      </code>
    </td>
    
    <td>
      The <a href="https://encodings.agntn.dev/guide/agents">
        MCP server
      </a>
      
       over stdio
    </td>
  </tr>
</tbody>
</table>

`-` 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:

```bash
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

```bash
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.

```bash
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

```bash
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.

```bash
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:

```bash
encodings decode base32 CPNMUOJ1E8 --alphabet hex
# foobar
```

## Identify

```bash
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.

```bash
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](https://encodings.agntn.dev/guide/identify#encoded-twice-peel-it).

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.

```bash
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.


## Sitemap

See the full [sitemap](https://encodings.agntn.dev/sitemap.md) for all pages.
