Upload a file
  1. base64hub
  2. Docs
  3. CLI

b64 CLI Reference

b64 encodes, decodes and validates Base64. This page lists every flag, the rules for combining them, and what the command prints and returns.

Install

MethodCommand
Homebrew (macOS, Linux)brew install base64hub-com/tap/b64
Scoop (Windows)scoop bucket add base64hub https://github.com/base64hub-com/homebrew-tap, then scoop install b64
winget (Windows)winget install base64hub.b64
AUR (Arch Linux)yay -S b64-bin
Install scriptcurl -fsSL https://base64hub.com/install.sh | sh
npmnpm i -g base64hub
pipxpipx install base64hub
Gogo install github.com/base64hub-com/base64hub-cli/cmd/b64@latest

Release archives for macOS, Linux and Windows on x86_64 and arm64, .deb packages and a SHA256SUMS file are on the download page. Check the installation with b64 --version, which prints b64 1.0.0.

The npm and pipx builds are the same command with the same flags and messages. The one difference: the Go build streams standard input in chunks, while the npm and Python builds read the whole input into memory first.

Usage

b64 [flags] [TEXT]

With TEXT, b64 works on the UTF-8 bytes of TEXT, with no newline added. Without TEXT it reads standard input to the end, or the file given with -i. Flags may come before or after TEXT.

Encoding prints the Base64 followed by one newline. Decoding writes the raw bytes and nothing else, so the output of b64 -d can be a binary file.

Flags

FlagMeaning
-d, --decodeDecode Base64 to raw bytes.
-u, --urlEncode with the URL-safe alphabet (- and _).
-n, --no-padEncode without = padding.
-w N, --wrap NWrap encoded output every N characters; 0 (default) is no wrapping, 76 is MIME.
--data-uriEncode as a data: URI; the MIME type is detected from the content.
-m TYPE, --mime TYPEMIME type for --data-uri.
--validateCheck the input and report its variant and decoded size.
-i FILE, --input FILERead FILE instead of standard input; - means standard input.
-o FILE, --output FILEWrite FILE instead of standard output; - means standard output.
-h, --helpShow the help.
-v, --versionPrint b64 and the version.
--End of flags: the next argument is TEXT even if it starts with -.

Rules for combining flags

  • Short flags cannot be bundled: -dn is an unknown option. Values go after a space (-w 4) or, for long flags, after = (--wrap=4); -w4 is not accepted.
  • -u, -n, -w and --data-uri apply to encoding only; with -d or --validate they are usage errors.
  • -d and --validate cannot be combined.
  • --data-uri always uses the standard alphabet with padding on one line, so -u, -n and -w cannot be combined with it.
  • --mime needs --data-uri.
  • TEXT and -i cannot be used together, and only one TEXT is allowed: quote text that contains spaces.
  • TEXT that starts with -, such as URL-safe Base64, needs -- in front of it: b64 -d -- -_-_.

Exit codes and messages

CodeMeaning
0Success.
1Invalid input, or a file could not be read or written.
2Usage error: unknown flag, bad value, or flags that cannot be combined.

Errors go to standard error as b64: <message>. --validate prints valid (<variant>, <bytes> bytes) to standard output for valid input, and invalid: <reason> to standard error with exit code 1 otherwise.

$ b64 -d 'Zm9v!'
b64: invalid character '!' at position 4
$ b64 -d 'Zm=9v'
b64: unexpected '=' at position 2: padding is only allowed at the end
$ b64 -d 'Zg==='
b64: too much padding: 3 '=' at position 2, at most 2 are allowed
$ b64 -d 'Zm9vY'
b64: invalid length: 5 characters leave a single character in the last group
$ b64 -d -u Zm9v
b64: --url only applies to encoding, not to --decode

Positions count from 0 in the input after spaces, tabs and line breaks are removed.

Examples

Encode and decode text:

$ b64 "Hello, hub!"
SGVsbG8sIGh1YiE=
$ b64 -d SGVsbG8sIGh1YiE=
Hello, hub!

URL-safe, with and without padding:

$ printf '\xfb\xff\xbf' | b64 --url
-_-_
$ b64 --url --no-pad "Привет"
0J_RgNC40LLQtdGC
$ b64 -n f
Zg

Wrap lines, and note that echo adds a newline that gets encoded too:

$ b64 -w 4 foobar
Zm9v
YmFy
$ echo hello | b64
aGVsbG8K

Data URIs, detected or with an explicit type:

$ b64 --data-uri Hello
data:text/plain;charset=utf-8;base64,SGVsbG8=
$ b64 --data-uri -m text/csv 'a,b'
data:text/csv;base64,YSxi
$ b64 --data-uri -i logo.png -o logo.txt

Decoding is lenient: line breaks, a data: prefix and missing padding are accepted, and a string that starts with - goes after --:

$ b64 -d 'data:text/plain;base64,SGk='
Hi
$ b64 -d -- -_-_ | xxd -p
fbffbf

Validate in a script:

$ b64 --validate SGVsbG8sIGh1YiE=
valid (either, 11 bytes)
$ b64 --validate 'a+b_'
valid (mixed, 3 bytes)
if b64 --validate -i token.txt >/dev/null 2>&1; then
  echo "token looks like Base64"
else
  echo "token is broken" >&2
fi

Files in and out:

b64 -i photo.jpg -o photo.b64
b64 -d -i photo.b64 -o photo-copy.jpg

Detected MIME types

--data-uri without --mime looks at the first bytes: PNG, JPEG, GIF, WebP and PDF by their signatures, and SVG when the text starts with <svg, or with <?xml and contains <svg. Other valid UTF-8 text without control characters (tab, CR and LF are fine) becomes text/plain;charset=utf-8; everything else application/octet-stream.

Updated Nov 22, 2026