threadpanic/rustpg
1
0
Fork
You've already forked rustpg
0
4 CLI Reference
Bert van der Weerd edited this page 2026年05月18日 17:37:36 +02:00
Table of Contents

CLI Reference (rpg)

rpg is the command-line binary. It shares the same keyring, config file, and crypto library (rpglib) as the GUI — operations done in one are immediately visible in the other.

Invocation

rpg [FLAGS] [OPTIONS] [FILE]

When called with no arguments and stdin is a terminal, rpg prints help. When stdin is a pipe and no operation is specified, it exits with an error.

Keyring password resolution

Every operation that touches the keyring needs the master password that protects key_material.rpg. The password is resolved in this order:

  1. RPG_KEYRING_PASSWORD environment variable — process-list safe, recommended for scripts
  2. --keyring-password-file <PATH> — reads the password from a file (trailing newline stripped)
  3. OS keyring (passwd_keyring entry under service rustpg) — used when remember_password = true in rustpg.conf
  4. Interactive prompt (rpassword) — terminal prompt, no echo

--keyring-password <PASS> is also accepted but not recommended: the value is visible in ps aux output and recorded in shell history. A stderr warning is printed when it is used.

If no keyring file exists yet (first run), no password is required.

Input and output

All crypto operations accept an optional positional FILE argument and an optional --output FILE flag:

Input Output
FILE argument --output FILE
stdin (pipe) stdout

The two can be mixed freely — e.g. read from stdin, write to a file.

Crypto operations

--symmetric / -c — symmetric encrypt

AES-256-GCM with Argon2id key derivation. Passphrase from --passphrase or prompted interactively.

rpg --symmetric --passphrase "secret" document.txt -o document.txt.rpg
rpg -c --passphrase "secret" -a document.txt # armored output to stdout

--symmetric --stream <FILE> — stream encrypt (LFM)

ChaCha20-Poly1305 + Argon2id, streaming file-to-file. No keyring needed. Output is written to <FILE>.rpgx. No --output flag — the output path is always derived from the input path.

rpg --symmetric --stream video.mp4 --passphrase "secret"
# writes video.mp4.rpgx

--encrypt / -e — asymmetric encrypt

X25519 ECIES + AES-256-GCM. Requires --recipient.

rpg --encrypt --recipient alice document.txt -o document.txt.rpg
rpg -e -r alice -a document.txt # armored to stdout

--encrypt --sign — sign-then-encrypt

Ed25519-signs the plaintext (binary mode) then ECIES-encrypts the signed blob. Requires --recipient for the encryption key; --my-id selects the signing key (defaults to own identity).

rpg --encrypt --sign --recipient alice --my-id bert document.txt -o out.rpg

After decryption the receiver sees Good signature from bert. (or a warning) on stderr if they pass --recipient bert.

--decrypt / -d — decrypt

Auto-detects RPGS (symmetric) or RPGA (asymmetric) from the 4-byte magic. For symmetric, --passphrase or prompt. For asymmetric, --my-id selects the private key (defaults to own identity).

rpg --decrypt --passphrase "secret" document.txt.rpg
rpg -d --my-id bert encrypted.rpg -o plaintext.txt

If the decrypted payload contains an embedded signature, the wrapper is stripped automatically and the signature is reported to stderr.

--decrypt --stream <FILE> — stream decrypt (LFM)

Decrypts an RPGX stream file. Output path is <FILE> with the .rpgx extension stripped (or <FILE>.dec if no .rpgx extension).

rpg --decrypt --stream video.mp4.rpgx --passphrase "secret"
# writes video.mp4

Signing

--sign / -s — binary sign

Produces a single blob: RUSTPGSIG\x02 + 64-byte Ed25519 signature + original data. Output is binary; pipe through --armor for text.

rpg --sign document.txt -o document.txt.sig
rpg -s -a document.txt -o document.txt.asc

--clearsign — clear-sign

Wraps a UTF-8 text file in a human-readable armored block with the signature appended. Input must be valid UTF-8.

rpg --clearsign message.txt -o message.txt.asc

--detach-sign / -b — detached signature

Writes a raw 64-byte Ed25519 signature to a separate file. Share the signature alongside the original unchanged file.

rpg --detach-sign document.txt -o document.txt.sig

--verify — verify

Auto-detects binary, clearsign, or detached format. Use --sigfile for detached signatures. --recipient selects whose key to verify with; defaults to own identity.

rpg --verify --recipient alice signed.txt
rpg --verify --recipient alice --sigfile document.txt.sig document.txt

Prints Good signature. or BAD signature. to stdout.

Format

--armor / -a — ASCII armor

Wraps binary output in OpenPGP-style armor (base64 + CRC24). Can be combined with any crypto or sign operation.

rpg --encrypt -r alice -a document.txt # outputs -----BEGIN RUSTPG ASYMMETRIC MESSAGE-----

--dearmor — strip armor

Converts armored text back to binary. Accepts any -----BEGIN ... ----- header (RUSTPG or PGP).

rpg --dearmor document.txt.asc -o document.txt.rpg

Key management

--gen-key — generate keys

Generates a new X25519 (encryption) and Ed25519 (signing) keypair. Inserts or updates the identity with --my-id in the keyring. Prompts for confirmation if the slug already exists.

rpg --gen-key --my-id bert --name "Bert van der Weerd" --email "bert@example.com"

--list-keys / -k — list all identities

Shows all identities: role, display name, email, fingerprint, revocation status.

rpg --list-keys

pub [contact] Alice Doe <alice@example.com>
 AABBCCDD EEFF0011 22334455 ...
sec [self] Bert van der Weerd <bert@example.com>
 11223344 AABBCCDD EEFF0011 ...

--list-secret-keys / -K — list own identities

Same as --list-keys but restricted to identities with private keys.

--fingerprint — show fingerprint

Prints the SHA-256 fingerprint of the Ed25519 public key for the selected identity.

rpg --fingerprint --my-id bert
rpg --fingerprint # defaults to own identity

--export — export public identity

Outputs a rustpg-keyring block with public keys only. The role is downgraded to contact — safe to share.

rpg --export --my-id bert -o bert-public.txt
rpg --export --recipient alice -o alice-public.txt

--export-secret-keys — export full identity

Includes private keys. Keep this output confidential.

rpg --export-secret-keys --my-id bert -o bert-full.txt

--import — import identities

Parses a rustpg-keyring file and merges all identities into the keyring. Slug conflicts are refused.

rpg --import alice-public.txt

--gen-revoke — generate revocation certificate

Produces a -----BEGIN RUSTPG REVOCATION----- PEM block — an Ed25519 signature over the literal bytes REVOKE. Stores the cert in the keyring and writes it to the output.

rpg --gen-revoke --my-id bert -o bert-revoke.pem

--import-revoke — apply a revocation certificate

Reads a revocation cert, finds the matching identity by verifying the cert against every Ed25519 key in the keyring, and marks it revoked.

rpg --import-revoke alice-revoke.pem

--edit-key — edit key metadata

Not yet implemented.

Store type

By default rpg uses the RPG keystore at ~/.config/rustpg/key_material.rpg. Two flags select an alternate backend:

--storetype-rpg [PATH]

Use the RPG keystore. If PATH is given, open that file instead of the default. The OS vault is not consulted for alternate paths — supply the password via --keyring-password or the interactive prompt.

rpg --storetype-rpg /mnt/usb/backup.rpg --list-keys

--storetype-gnupg

Use GnuPG's ~/.gnupg as a read-only keystore. gpg must be in PATH. Only --list-keys and --list-secret-keys are supported; all write operations print an error.

rpg --storetype-gnupg --list-keys
rpg --storetype-gnupg --list-secret-keys

See KeyStore Architecture for the full backend design.

Common flags

Flag Short Description
--my-id <SLUG> Own identity slug. Default: my_id from rustpg.conf, then first self identity.
--recipient <SLUG> -r Recipient or signer slug. Default: last_recipient_id from rustpg.conf.
--keyring-password <PASS> Master password for key_material.rpg. Overrides OS vault.
--passphrase <PASS> Passphrase for symmetric encrypt/decrypt.
--output <FILE> -o Write output to FILE instead of stdout.
--sigfile <FILE> Detached signature file for --verify.
--cipher-algo <ALGO> Cipher for --symmetric. Currently only AES256 is implemented.
--stream <FILE> With --symmetric: stream-encrypt FILE to FILE.rpgx. With --decrypt: stream-decrypt FILE.rpgx → FILE.
--armor -a ASCII-armor output.
--name <NAME> Display name for --gen-key.
--email <EMAIL> Email address for --gen-key.
--verbose -v Verbose output.
--quiet -q Suppress informational output.
--version -V Print version and exit.
--storetype-rpg [PATH] Use RPG keystore (optional alternate path).
--storetype-gnupg Use GnuPG keystore (read-only).

Settings defaults (~/.config/rustpg/rustpg.conf)

rpg reads the shared config file on startup. Two fields affect CLI behaviour:

Key Effect
my_id Default value for --my-id when the flag is omitted
last_recipient_id Default value for --recipient when the flag is omitted

The config file is shared with the GUI — changing my_id in the GUI's Settings panel affects the CLI default and vice versa.

Common workflows

Encrypt a file for Alice and armor it:

rpg --encrypt --recipient alice --armor report.pdf -o report.pdf.asc

Decrypt any rustpg file (auto-detects symmetric/asymmetric):

rpg --decrypt encrypted.rpg -o plaintext.txt

Sign and encrypt in one step:

rpg --encrypt --sign --recipient alice document.txt -o document.rpg
# Alice decrypts and verifies:
rpg --decrypt --recipient bert document.rpg -o document.txt

Clearsign a text announcement:

rpg --clearsign --my-id bert announcement.txt -o announcement.txt.asc

Verify a clearsigned or binary-signed file:

rpg --verify --recipient bert announcement.txt.asc

Export your public key and send it to a contact:

rpg --export --my-id bert -o bert.txt
# Contact imports it:
rpg --import bert.txt

Revoke your key and distribute the certificate:

rpg --gen-revoke --my-id bert -o bert-revoke.pem
# Contacts apply it:
rpg --import-revoke bert-revoke.pem

Pipe from stdin:

echo "hello" | rpg --symmetric --passphrase "pw" --armor
cat encrypted.asc | rpg --dearmor | rpg --decrypt --passphrase "pw"

Stream-encrypt and decrypt a large file (LFM):

rpg --symmetric --stream video.mp4 --passphrase "secret" # → video.mp4.rpgx
rpg --decrypt --stream video.mp4.rpgx --passphrase "secret" # → video.mp4