base64: Usage, Options & Common CI Errors
base64 turns binary data into ASCII text and back, so it can travel through text-only channels.
base64 is how secrets, certs, and small binaries get passed through env vars and YAML in CI. The recurring bug is line wrapping - GNU wraps at 76 columns by default, which corrupts single-line secrets.
What it does
base64 encodes arbitrary bytes into the 64-character Base64 alphabet (and decodes with -d). It is used to embed binary data - keys, certificates, kubeconfigs - inside text-only formats like environment variables and YAML.
Common usage
base64 file.bin > file.b64
base64 -d file.b64 > file.bin # decode
echo -n "secret" | base64 # encode a string
base64 -w0 cert.pem # no line wrapping (GNU)
echo "$B64" | base64 --decode > key.pemOptions
| Flag | What it does |
|---|---|
| -d / --decode | Decode instead of encode |
| -w <N> / --wrap=N | Wrap encoded lines at N cols (0 = none, GNU) |
| -i / --ignore-garbage | Skip non-alphabet bytes when decoding |
| -b <N> | BSD/macOS line-break column (instead of -w) |
Common errors in CI
base64: invalid input - the data has embedded newlines/spaces or was truncated; GNU base64 wraps at 76 cols by default, so an unwrapped secret read back through a single-line env var breaks. Encode with -w0 (GNU) to keep it on one line; macOS/BSD uses -b 0 and -D for decode (capital D), not -d. Also echo adds a trailing newline - use echo -n or printf when encoding exact bytes.