How do I encrypt a file for someone with the bge CLI?

Use their public key: bge encrypt report.pdf -r alice.pub.pem. The result, report.pdf.bge, can only be opened by the holder of the matching private key. The recipient's key can be a .pem, a .bgekey identity card, or a saved contact name.

How do I encrypt a file to someone by name?

Save their public key once with bge contact add alice.pub.pem -n Alice, then encrypt by name: bge encrypt report.pdf -r Alice. The address book lives in ~/.bge and holds public keys only — never a private key.

How do I encrypt a file just for myself, as a backup?

With no recipient, bge seals the file to your own active identity: bge encrypt taxes.pdf. Register one of your public keys as an identity first with bge identity add me.pub.pem -n Me. Only your private key can open it.

How do I encrypt a file with a password instead of keys?

Run bge encrypt report.pdf -p and enter a passphrase. Anyone who knows the passphrase can open it with bge decrypt report.pdf.bge -p — useful when you can't exchange keys ahead of time. In scripts, pipe the passphrase with --password-stdin instead of -p.

How do I decrypt a .bge file from the command line?

For an identity-encrypted file, use your private key: bge decrypt report.pdf.bge -k alice.pem. For a password-encrypted file: bge decrypt report.pdf.bge -p. Run bge inspect first if you're not sure which mode a file uses.

How do I find out who a .bge file is for without decrypting it?

Run bge inspect report.pdf.bge — it reads only the public header and reports the mode, key ID (RSA) or KDF (password), and size, with no key needed. If the recipient is in your address book, it also prints Encrypted for: .

How do I encrypt an entire folder with bge?

Two ways: bge encrypt myfolder -r Alice mirrors the tree into myfolder_bge/ with one .bge per file (browse and decrypt files individually); bge encrypt myfolder -a -r Alice zips the folder and encrypts it to one myfolder.zip.bge, which also hides the file names and count.

How do I bundle several files into one encrypted file?

Pass the files with -a (archive): bge encrypt a.pdf notes.txt photo.jpg -a -r Alice -o bundle.bge. bge zips them into a single .bge; you don't need to stage a temp folder yourself. Decrypt and unzip with bge decrypt bundle.bge -k alice.pem -x.

How do I encrypt or decrypt without leaving plaintext on disk?

Use stdin/stdout with -. For example, decrypt straight into tar: bge decrypt - -k alice.pem < archive.tgz.bge | tar xzf -. Status lines go to stderr, so stdout carries only data.

How do I run bge non-interactively in a script?

Prefer RSA keys (-r / -k) so there is no prompt. For password mode, pipe the passphrase with --password-stdin and never put it on the command line: printf %s "$PASSPHRASE" | bge encrypt notes.txt --password-stdin. Branch on the sysexits exit codes (64 usage, 65 data, 66 no input, 77 can't decrypt).

How do I share my key so others can encrypt files to me?

Wrap your public key into a .bgekey identity card: bge card alice.pub.pem -n "Alice". Send the Alice.bgekey file; the DotBGE apps import it as a contact, and other bge users can encrypt to you with bge encrypt file -r Alice.bgekey. No private key is ever read or shared.

How do I install the bge command-line tool?

On macOS, install with Homebrew: brew install --cask dotbge/tap/bge. On Linux, download the tarball for your architecture (x86_64 or aarch64) from the GitHub releases page and put the bge binary on your PATH. The macOS build is a signed, notarized universal binary; the Linux builds statically link the Swift runtime, so no Swift install is required.

Can I use bge with Claude Code or an AI agent?

Yes. The bge-cli repository ships a Claude Code skill (skills/bge-encryption) that teaches an agent how to drive bge. Copy it into ~/.claude/skills/ and ask in plain language, for example: encrypt report.pdf for Alice. See dotbge.app/agents for the scenarios it handles.

Are files encrypted with the bge CLI compatible with the DotBGE apps?

Yes. The CLI writes the same open .bge v3 format. A .bge file made in the terminal opens in the DotBGE apps for iPhone, iPad, and Mac, and .bgekey identity cards round-trip between them. The CLI uses file-based keys only and never stores private keys.

The bge CLI — Encrypt files from the command line (macOS & Linux)

The bge command-line tool is the terminal companion to the DotBGE apps. It writes the open .bge format — RSA-4096-OAEP for sealing a file to a person, AES-256-GCM for the contents — with no servers, no accounts, and nothing to lock you in. .bge files and .bgekey identity cards round-trip with the apps for iPhone, iPad, and Mac.

Install

macOS · Homebrew

brew install --cask dotbge/tap/bge

The macOS build is a universal binary (Apple Silicon and Intel), signed with an Apple Developer ID and notarized, so it runs without Gatekeeper warnings. You can also download a .pkg or the standalone .zip from the releases page.

Linux (x86_64 or aarch64)

# download the tarball for your arch from the releases page, then:
tar xzf bge-<version>-linux-x86_64.tar.gz
sudo install bge-<version>-linux-x86_64/bge /usr/local/bin/bge
bge --version

The Linux binaries statically link the Swift runtime, so they run on any recent glibc-based distribution — no Swift install required.

Verify a download: shasum -a 256 -c SHA256SUMS (macOS) · sha256sum -c SHA256SUMS-linux (Linux).

Quick start

# 1. Make an identity key pair
bge keygen -o alice                        # → alice.pem (private) + alice.pub.pem

# 2. Encrypt for someone — only their private key can open it
bge encrypt report.pdf -r alice.pub.pem    # → report.pdf.bge

# 3. Decrypt with your private key
bge decrypt report.pdf.bge -k alice.pem    # → report.pdf

Run bge -h, or bge <command> -h, for every option. enc / dec are aliases for encrypt / decrypt.

How do I…?

The most common tasks, each as a one-liner. bge never overwrites by default — add -f only when you mean to.

Encrypt a file for someone?

You need their public key — a .pem, a .bgekey card, or a saved contact name. Only their private key can open the result.

bge encrypt report.pdf -r alice.pub.pem    # → report.pdf.bge

Encrypt to someone by name?

Save their key once, then encrypt by name. The address book lives in ~/.bge and holds public keys only.

bge contact add alice.pub.pem -n Alice
bge encrypt report.pdf -r Alice            # name is case-insensitive

Encrypt a file just for myself (a backup)?

With no recipient, bge seals the file to your own active identity — only your private key opens it.

bge identity add me.pub.pem -n Me          # once
bge encrypt taxes.pdf                       # → sealed to you

Encrypt with a password instead of keys?

Good when you can't exchange keys ahead of time — anyone with the passphrase can open it.

bge encrypt report.pdf -p                  # prompts for a passphrase

Decrypt a .bge file?

bge decrypt report.pdf.bge -k alice.pem    # identity → report.pdf
bge decrypt report.pdf.bge -p              # password file → prompts

Find out who a .bge file is for?

Keyless — reads only the public header. If the recipient is in your address book, it also prints Encrypted for: <name>.

bge inspect report.pdf.bge                 # mode, key ID, size — no key needed

Encrypt an entire folder?

Mirror the tree (browse files individually) or pack it into one archive that also hides the file names.

bge encrypt myfolder -r Alice              # → myfolder_bge/ (one .bge per file)
bge encrypt myfolder -a -r Alice           # → myfolder.zip.bge (one archive)

Bundle several files into one encrypted file?

Pass them with -a — bge zips and encrypts them for you; no temp folder needed.

bge encrypt a.pdf notes.txt photo.jpg -a -r Alice -o bundle.bge
bge decrypt bundle.bge -k alice.pem -x     # decrypt + unzip

Avoid leaving decrypted content on disk?

Pipe through stdin/stdout with -. Status goes to stderr, so stdout carries only data.

bge decrypt - -k alice.pem < archive.tgz.bge | tar xzf -

Run bge non-interactively in a script?

Prefer RSA keys (no prompt). For password mode, pipe the passphrase with --password-stdin — never put a secret on the command line.

printf %s "$PASSPHRASE" | bge encrypt notes.txt --password-stdin

Branch on the sysexits exit codes: 64 usage · 65 data · 66 no input · 77 can't decrypt.

Share my key so others can encrypt to me?

Wrap your public key into a .bgekey card the DotBGE apps import as a contact. No private key is read.

bge card alice.pub.pem -n "Alice"          # → Alice.bgekey

For Claude Code & AI agents

Let an agent do the encrypting

The repository ships a Claude Code skill so you can just ask — “encrypt report.pdf for Alice”, “decrypt this and summarise it” — and the agent runs bge safely, with no plaintext left lying around.

See bge for Claude Code & AI agents → — the scenarios it handles, the guardrails, and how to install the skill.

An open format, not a silo

The CLI uses file-based keys only and never stores private keys. It writes the same open .bge v3 container the apps do — documented, with test vectors, so your files outlive any single tool.

bge on GitHub Read the .bge spec ↗