Base100 encoding maps every UTF-8 byte to one emoji-range code point, from U+1F3F7 (byte 0) to U+1F4F6 (byte 255), using the formula code point = U+1F3F7 + byte value. The same byte-plus-offset formula sits inside both command-line scripts and browser-based encoders, but the two delivery methods diverge sharply in setup, validation, and how they handle the symbol stream around the edges. A command-line tool runs inside a terminal, pipes bytes through the same mapping, and hands the result back through stdout or a file redirect. An online encoder wraps the identical formula in a browser form: you paste text, the page maps bytes to code points in memory, and you copy the result as a symbol stream without anything being uploaded. The choice between them usually comes down to whether the task is automated (scripted, batched, embedded in a build) or interactive (a one-off conversion, decoding a stream someone sent, sanity-checking a paste that looks wrong).
How the Base100 Mapping Actually Works
Base100 is the byte-to-code-point mapping originally published by Adam Niederer in the base100 GitHub project. The encoding converts the input string to UTF-8 first, then takes every resulting byte b in the range 0–255 and emits the single Unicode code point U+1F3F7 + b. There are exactly 256 code points in the output alphabet, sitting contiguously from U+1F3F7 through U+1F4F6 in the supplementary multilingual plane. The mapping is one-to-one, so the same code point always represents the same byte, and decoding is just subtraction followed by UTF-8 reconstruction.
Worked example: take byte value 65, the ASCII letter A. 0x1F3F7 equals 127,991 in decimal, and 127,991 + 65 = 128,056, which is U+1F438. So one ASCII "A" in the input produces exactly one U+1F438 symbol in the output. Byte 255 produces U+1F4F6 (127,991 + 255 = 128,246, which is 0x1F4F6 in hexadecimal), and byte 0 produces U+1F3F7 itself. No padding, delimiter, checksum, length marker, or semantic translation is inserted between the bytes — the output length is always exactly equal to the number of UTF-8 bytes in the input.
That byte-level framing is what makes the choice between command line and online more interesting than it first looks. Both modes must convert the input to UTF-8, walk the bytes one at a time, and apply the offset. The differences come from how each mode accepts input, how it surfaces errors, and what happens around the edges of the mapping — including the common gotcha that one user-typed character can expand to several UTF-8 bytes and therefore several Base100 symbols.
Command Line vs Online: A Side-by-Side Comparison
| Dimension | Command-line Base100 | Online Base100 encoder |
|---|---|---|
| Setup | Install a CLI implementation (original Rust binary or a port in Python, Go, or another language) | Open the page; no installation |
| Network | Only required for the one-time install | Only required to load the page; conversion runs locally after that |
| Input channel | stdin pipe, file redirect, or argument | Textarea paste |
| Output channel | stdout stream, redirectable to a file | Symbol stream displayed on the page, copyable to the clipboard |
| UTF-8 boundary | Handled by the runtime and the OS locale | Handled by the browser per the WHATWG Encoding Standard |
| Strict decode behavior | Depends on the implementation | Rejects spaces, line breaks, variation selectors, and out-of-range code points; reports invalid UTF-8 as an error |
| Scriptable | Yes — fits pipes, loops, and build steps | Not directly; needs automation tooling around the page |
| Input privacy | Local by default | Local by default when conversion runs in the browser |
| Accidental huge paste | Truncated by the shell or filesystem, not by the tool | Capped at 500,000 bytes or symbols to protect the tab |
The two columns share the mathematical core. They diverge on ergonomics: a CLI fits cleanly into a pipeline or a CI step, while a browser tool fits cleanly into a one-off task where the input is already in your clipboard or was sent to you as a message.
Run Base100 From the Command Line
The original implementation is the Rust project by Adam Niederer; several ports in Python, Go, and other languages implement the same byte-plus-offset formula. Whatever runtime you pick, the workflow is the same:
- Install or build a Base100 CLI. With the original Rust source, build it with cargo; with a Python port, install it with pip; with a Go port, install it with go install. Pick the one that matches the rest of your toolchain.
- Prepare the input as UTF-8. Save the message to a file, or pipe it in from another command. Make sure the terminal locale produces UTF-8, because a non-ASCII text expanded under the wrong encoding will encode the wrong bytes and round-trip back to garbage.
- Invoke the encoder, sending the UTF-8 input on stdin or as a file argument. The tool walks the bytes, applies U+1F3F7 + b to each one, and writes the resulting code points to stdout as a single uninterrupted symbol stream.
- Capture the output. Redirect stdout into a file if you need to share it, or copy the stream straight from the terminal. Do not add spaces, line breaks, or variation selectors when copying — the strict decoder will reject them.
- To decode, reverse the direction: pipe the Base100 stream into the decoder, or pass it as an argument. A strict decoder subtracts U+1F3F7 from every code point, checks the result is in 0–255, and reinterprets the bytes as UTF-8.
- Sanity-check the round trip. Encoding then decoding the same UTF-8 text should return the original characters. Any mismatch means a symbol was dropped, a variation selector was added, or a code point was substituted in transit.
The CLI works well inside a shell pipeline because Base100 has no framing overhead to strip: no padding, no header, no checksum, no length marker. The downside is the same reason: there is no built-in check that a copied-and-pasted stream is intact, so a single character substitution produces a single-byte change in the decoded text with no warning flag.
Encode or Decode Base100 in Your Browser
The browser version of the same formula lives at the Base100 Encoder / Decoder page, and the steps mirror the CLI flow but trade stdout pipes for a textarea:
- Choose Text to Base100 if you want to encode, or Base100 to text if you want to decode.
- Paste your UTF-8 text (for encoding) or a Base100 symbol stream (for decoding) into the input area. Empty input is rejected rather than silently producing empty output.
- Run the conversion. The encoder maps every UTF-8 byte to one code point in U+1F3F7–U+1F4F6; the decoder subtracts the offset and validates the result as UTF-8.
- Copy the output from the result area. Do not add spaces, line breaks, punctuation, or variation selectors when copying — the strict decoder will reject them on the way back in.
- If decoding fails with an error, the bytes were not a valid UTF-8 sequence or the input contained a code point outside the Base100 range. The page reports the failure rather than silently substituting replacement characters and pretending the result is exact.
Because the conversion runs locally in the browser, the input is never uploaded to a server. The page enforces a 500,000-byte or 500,000-symbol cap in either direction so a runaway paste cannot freeze the tab, and output inside that cap is never silently truncated.
Why the Symbol Count Does Not Match the Character Count
The single most common surprise when comparing command line and online behavior is output length. A 10-character ASCII message always produces 10 Base100 symbols, because each ASCII character is exactly one UTF-8 byte. A 10-character string that contains accented letters, CJK ideographs, or emoji usually produces more than 10 symbols, because those characters are encoded as multiple UTF-8 bytes and Base100 maps bytes, not characters. The symbol count is therefore a count of encoded bytes, not user-perceived characters, grapheme clusters, words, or the JavaScript string length of the input. If the CLI and the online tool ever disagree on length for the same input, the cause is almost always a locale mismatch (the CLI encoded a different byte sequence than the browser did) rather than a difference in the formula itself.
When a Stream Fails to Decode
Strict decoding rejects anything that is not the exact 256-code-point alphabet. Spaces, line breaks, punctuation, variation selectors, and emoji outside U+1F3F7–U+1F4F6 are not framing syntax in the original format; they are accidental decorations introduced by chat apps, editors, keyboards, or normalization pipelines. A stream that looks visually similar on screen can be bytewise different and fail the strict check. When that happens, re-copy the original stream from a source that does not transform Unicode — a plain text editor, a hex dump, or a programmatic export — and try again. The page reports invalid UTF-8 as a hard error rather than silently inserting U+FFFD replacement characters, so a failed decode means the bytes really are wrong, not that the tool is being cautious.
Choosing the Right Approach for the Job
Pick the command line when the task is repeatable: a build step, a script that processes a folder of files, anything that has to run unattended. Pick the online tool when the task is one-off: a suspicious paste, a stream someone forwarded, a snippet you want to encode for a chat message, or a quick round-trip check after editing a file. The shared formula means you can move between the two without surprises, as long as both ends agree on UTF-8 at the boundary and as long as no character in the stream has been transformed in transit. For the full local-runner perspective, the guide on running the Base100 mapping locally as an API alternative walks through the same byte-plus-offset formula in a scriptable form.