Rage

https://github.com/str4d/rage
Admin
Rage is a simple, modern, and secure file encryption tool implementing the age format, featuring...
Tokens:33,934
Snippets:222
Trust Score:9.1
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install rage with Scoop

Source: https://github.com/str4d/rage/blob/main/README.md

Install rage via Scoop on Windows. First add the main bucket, then install the rage package.

```bash
scoop bucket add main
```

```bash
scoop install main/rage
```

--------------------------------

### Install rage with nix-env

Source: https://github.com/str4d/rage/blob/main/README.md

Install rage globally with nix-env.

```bash
nix-env -i rage
```

--------------------------------

### Install rage with pkg

Source: https://github.com/str4d/rage/blob/main/README.md

Install rage via FreeBSD package manager.

```bash
pkg install rage-encryption
```

--------------------------------

### Install rage with Homebrew

Source: https://github.com/str4d/rage/blob/main/README.md

Install rage via Homebrew on macOS or Linux.

```bash
brew install rage
```

--------------------------------

### Install rage with zypper

Source: https://github.com/str4d/rage/blob/main/README.md

Install rage via openSUSE Tumbleweed package manager.

```bash
zypper install rage-encryption
```

--------------------------------

### Install rage with MacPorts

Source: https://github.com/str4d/rage/blob/main/README.md

Install rage via MacPorts.

```bash
port install rage
```

--------------------------------

### Install rage with apk

Source: https://github.com/str4d/rage/blob/main/README.md

Install rage via Alpine Linux (edge) package manager.

```bash
apk add rage
```

--------------------------------

### Install rage with pacman

Source: https://github.com/str4d/rage/blob/main/README.md

Install rage via Arch Linux package manager.

```bash
pacman -S rage-encryption
```

--------------------------------

### Install cargo-deb

Source: https://github.com/str4d/rage/blob/main/docs/debian.md

Install the cargo-deb tool, which is required to build Debian packages for rage.

```bash
cargo install cargo-deb
```

--------------------------------

### Example age plugin binary with clap

Source: https://github.com/str4d/rage/blob/main/age-plugin/README.md

Example age plugin binary using clap to parse CLI arguments. It implements RecipientPluginV1 and IdentityPluginV1, and runs the state machine when the --age-plugin flag is present. Any argument parsing logic works as long as it can detect the --age-plugin=STATE_MACHINE flag.

```rust
use age_core::format::{FileKey, Stanza};
use age_plugin::{
    identity::{self, IdentityPluginV1},
    print_new_identity,
    recipient::{self, RecipientPluginV1},
    Callbacks, run_state_machine,
};
use clap::Parser;

use std::collections::HashMap;
use std::io;

struct RecipientPlugin;

impl RecipientPluginV1 for RecipientPlugin {
    fn add_recipient(
        &mut self,
        index: usize,
        plugin_name: &str,
        bytes: &[u8],
    ) -> Result<(), recipient::Error> {
        todo!()
    }

    fn add_identity(
        &mut self,
        index: usize,
        plugin_name: &str,
        bytes: &[u8]
    ) -> Result<(), recipient::Error> {
        todo!()
    }

    fn wrap_file_keys(
        &mut self,
        file_keys: Vec<FileKey>,
        mut callbacks: impl Callbacks<recipient::Error>,
    ) -> io::Result<Result<Vec<Vec<Stanza>>, Vec<recipient::Error>>> {
        todo!()
    }
}

struct IdentityPlugin;

impl IdentityPluginV1 for IdentityPlugin {
    fn add_identity(
        &mut self,
        index: usize,
        plugin_name: &str,
        bytes: &[u8]
    ) -> Result<(), identity::Error> {
        todo!()
    }

    fn unwrap_file_keys(
        &mut self,
        files: Vec<Vec<Stanza>>,
        mut callbacks: impl Callbacks<identity::Error>,
    ) -> io::Result<HashMap<usize, Result<FileKey, Vec<identity::Error>>>> {
        todo!()
    }
}

#[derive(Debug, Parser)]
struct PluginOptions {
    #[arg(help = "run the given age plugin state machine", long)]
    age_plugin: Option<String>,
}

fn main() -> io::Result<()> {
    let opts = PluginOptions::parse();

    if let Some(state_machine) = opts.age_plugin {
        // The plugin was started by an age client; run the state machine.
        run_state_machine(
            &state_machine,
            Some(|| RecipientPlugin),
            Some(|| IdentityPlugin),
        )?;
        return Ok(());
    }

    // Here you can assume the binary is being run directly by a user,
    // and perform administrative tasks like generating keys.

    Ok(())
}
```

--------------------------------

### Install rage with Cargo

Source: https://github.com/str4d/rage/blob/main/README.md

Install rage via Cargo. Requires Rust 1.85 or later.

```bash
cargo install rage
```

--------------------------------

### rage CLI usage and options

Source: https://github.com/str4d/rage/blob/main/README.md

Shows the full command-line usage for the rage encryption tool, including arguments, options, and detailed explanations of RECIPIENT, PATH, and IDENTITY formats. INPUT defaults to standard input, OUTPUT defaults to standard output, and existing OUTPUT files are overwritten.

```text
Usage: rage [--encrypt] (-r RECIPIENT | -R PATH)... [-i IDENTITY] [-a] [-o OUTPUT] [INPUT]
       rage [--encrypt] --passphrase [-a] [-o OUTPUT] [INPUT]
       rage --decrypt [-i IDENTITY] [-o OUTPUT] [INPUT]

Arguments:
  [INPUT]  Path to a file to read from.

Options:
  -h, --help                    Print this help message and exit.
  -V, --version                 Print version info and exit.
  -e, --encrypt                 Encrypt the input (the default).
  -d, --decrypt                 Decrypt the input.
  -p, --passphrase              Encrypt with a passphrase instead of recipients.
      --max-work-factor <WF>    Maximum work factor to allow for passphrase decryption.
  -a, --armor                   Encrypt to a PEM encoded format.
  -r, --recipient <RECIPIENT>   Encrypt to the specified RECIPIENT. May be repeated.
  -R, --recipients-file <PATH>  Encrypt to the recipients listed at PATH. May be repeated.
  -i, --identity <IDENTITY>     Use the identity file at IDENTITY. May be repeated.
  -j <PLUGIN-NAME>              Use age-plugin-PLUGIN-NAME in its default mode as an identity.
  -o, --output <OUTPUT>         Write the result to the file at path OUTPUT.

INPUT defaults to standard input, and OUTPUT defaults to standard output.
If OUTPUT exists, it will be overwritten.

RECIPIENT can be:
- An age public key, as generated by rage-keygen ("age1...").
- An SSH public key ("ssh-ed25519 AAAA...", "ssh-rsa AAAA...").

PATH is a path to a file containing age recipients, one per line
(ignoring "#" prefixed comments and empty lines). "-" may be used to
read recipients from standard input.

IDENTITY is a path to a file with age identities, one per line
(ignoring "#" prefixed comments and empty lines), or to an SSH key file.
Passphrase-encrypted age identity files can be used as identity files.
Multiple identities may be provided, and any unused ones will be ignored.
"-" may be used to read identities from standard input.
```

--------------------------------

### Encrypt and decrypt with a passphrase using -p

Source: https://github.com/str4d/rage/blob/main/README.md

Encrypts example.png with a passphrase using -p/--passphrase, showing the autogenerated passphrase prompt, then decrypts it with -d. If a binary named pinentry is available in $PATH, it is used to ask for the passphrase; otherwise rage falls back to the CLI.

```bash
$ rage -p -o example.png.age example.png
Type passphrase (leave empty to autogenerate a secure one): [hidden]
Using an autogenerated passphrase:
    kiwi-general-undo-bubble-dwarf-dizzy-fame-side-sunset-sibling
$ rage -d example.png.age >example.png
Type passphrase: [hidden]
```

--------------------------------

### Encrypt using a recipients file with -R

Source: https://github.com/str4d/rage/blob/main/README.md

Shows creating a recipients file with one age public key per line (ignoring # comments) and then encrypting example.jpg using the -R/--recipients-file flag. If the argument to -R (or -i) is '-', the file is read from standard input.

```bash
$ cat recipients.txt
# Alice
age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
# Bob
age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg
$ rage -R recipients.txt example.jpg > example.jpg.age
```

--------------------------------

### Create and use a passphrase-protected identity file

Source: https://github.com/str4d/rage/blob/main/README.md

Creates a passphrase-protected identity file with rage-keygen, encrypts secrets.txt to the generated public key, and decrypts using the identity file with -i. Passphrase-protected identity files are useful when the identity file is stored remotely.

```bash
$ rage -p -o key.age <(rage-keygen)
Public key: age1pymw5hyr39qyuc950tget63aq8vfd52dclj8x7xhm08g6ad86dkserumnz
Type passphrase (leave empty to autogenerate a secure one): [hidden]
Using an autogenerated passphrase:
    flash-bean-celery-network-curious-flower-salt-amateur-fence-giant
$ rage -r age1pymw5hyr39qyuc950tget63aq8vfd52dclj8x7xhm08g6ad86dkserumnz secrets.txt > secrets.txt.age
$ rage -d -i key.age secrets.txt.age > secrets.txt
Type passphrase: [hidden]
```

--------------------------------

### Add rage to NixOS system packages

Source: https://github.com/str4d/rage/blob/main/README.md

Add rage to NixOS system packages in configuration.nix.

```nix
environment.systemPackages = [ pkgs.rage ];
```

--------------------------------

### Encrypt and decrypt with SSH keys

Source: https://github.com/str4d/rage/blob/main/README.md

Encrypts example.png to an SSH public key using -R and decrypts with the corresponding private key using -i. Supports ssh-rsa and ssh-ed25519 keys; ssh-agent is not supported. SSH key support embeds a public key tag in the encrypted file, making it possible to track files encrypted to a specific public key.

```bash
$ rage -R ~/.ssh/id_ed25519.pub example.png > example.png.age
$ rage -d -i ~/.ssh/id_ed25519 example.png.age > example.png
```

--------------------------------

### Encrypt to multiple recipients with -r

Source: https://github.com/str4d/rage/blob/main/README.md

Encrypts example.png to two recipients by repeating the -r/--recipient flag. Every recipient will be able to decrypt the file.

```bash
$ rage -o example.png.age -r age1uvscypafkkxt6u2gkguxet62cenfmnpc0smzzlyun0lzszfatawq4kvf2u \
    -r age1ex4ty8ppg02555at009uwu5vlk5686k3f23e7mac9z093uvzfp8sxr5jum example.png
```

--------------------------------

### Build Debian package with cargo deb

Source: https://github.com/str4d/rage/blob/main/docs/debian.md

Build the Debian package for the rage crate using cargo-deb.

```bash
cargo deb --package rage
```

--------------------------------

### Test localization with LANG environment variable

Source: https://github.com/str4d/rage/blob/main/docs/CONTRIBUTING.md

Commands to test localization locally by setting the LANG environment variable to your locale. Use cargo run with the appropriate binary and arguments, such as --help or other ARGUMENTS.

```shell
$ LANG=your-locale cargo run --bin rage -- --help
$ LANG=your-locale cargo run --bin rage -- ARGUMENTS
$ LANG=your-locale cargo run --bin rage-keygen -- --help

```

--------------------------------

### Fluent localization string format

Source: https://github.com/str4d/rage/blob/main/docs/CONTRIBUTING.md

Shows the Fluent format used for localization strings in the age and rage i18n directories. The identifier before the '=' is not translated, while the text after is. Multiline strings can contain paragraphs and may include terms and variables.

```fluent
some-unique-identifier = Translate the content on this side of the '=' symbol.
another-unique-identifier =
    This is a multiline string that can contain one or more paragraphs. Like
    above, the 'another-unique-identifier =' part is not translated, but this
    text is.

    Individual paragraphs should be line-wrapped at roughly the same number of
    characters as the corresponding English text, so that it looks roughly the
    same. Remember that {-terms} and {$variables} won't necessarily be the same
    length once filled in.

```

--------------------------------

### Add age dependency to Cargo.toml

Source: https://github.com/str4d/rage/blob/main/age/README.md

Add this line to your Cargo.toml to depend on the age crate version 0.11.

```toml
age = "0.11"
```
Tokens:
Raw