#totp #aegis #2fa #json-file #cli

app aegis-cli

Show TOTPs from Aegis vault on CLI

5 stable releases

new 1.2.1 Oct 30, 2024
1.1.1 Oct 26, 2024
1.1.0 Oct 25, 2024
1.0.7 Oct 24, 2024

#37 in Authentication

Download history 300/week @ 2024-10-23

300 downloads per month

GPL-3.0-or-later

31KB
276 lines

ci dependency status License: GPL v3 downloads

aegis-cli 1.2.1

Show TOTPs from Aegis vault on CLI

CLI app for showing TOTP codes from an Aegis vault file (backup file from the Aegis Authenticator Android app Aegis Authenticator).

Features

  • Decryption of the 256 bit AES-GCM encrypted vault 🔓
  • Fuzzy selection 🔍
  • TOTP display 🕒
  • Clears the screen when done ☐
  • Time left indication ⏳
  • Clipboard support 📋
  • Optional JSON output to stdout 📜
  • Optional URL output to stdout 📜

Installation

Download static single-binary

wget https://github.com/pepa65/aegis-cli/releases/download/1.2.1/aegis
sudo mv aegis /usr/local/bin
sudo chown root:root /usr/local/bin/aegis
sudo chmod +x /usr/local/bin/aegis

Using cargo (rust toolchain)

If not installed yet, install a Rust toolchain, see https://www.rust-lang.org/tools/install

Cargo from crates.io

cargo install aegis-cli

Cargo from git

cargo install --git https://github.com/pepa65/aegis-cli

Cargo static build (avoid GLIBC incompatibilities)

git clone https://github.com/pepa65/aegis-cli
cd aegis-cli
rustup target add x86_64-unknown-linux-musl
export RUSTFLAGS='-C target-feature=+crt-static'
cargo build --release --target=x86_64-unknown-linux-musl

Install with cargo-binstall

Even without a full Rust toolchain, rust binaries can be installed with the static binary cargo-binstall:

# Install cargo-binstall for Linux x86_64
# (Other versions are available at https://crates.io/crates/cargo-binstall)
wget github.com/cargo-bins/cargo-binstall/releases/latest/download/cargo-binstall-x86_64-unknown-linux-musl.tgz
tar xf cargo-binstall-x86_64-unknown-linux-musl.tgz
sudo chown root:root cargo-binstall
sudo mv cargo-binstall /usr/local/bin/

Only a linux-x86_64 (musl) binary available: cargo-binstall aegis-cli

Then aegis will be installed in ~/.cargo/bin/ which will need to be added to PATH!

Usage

Launching Aegis-cli with an Aegis vault file

To start aegis-cli, simply pass the path to your backup file as an argument and enter the password when prompted. For example:

aegis aegis-backup-20230512-193110.json

? Insert Aegis Password › ********

Searching for an Entry

Fuzzy finding is supported for quickly locating entries. Type some letters of the entry's name to filter the list. Pressing Esc exits the app.

Displaying the OTP

After an entry is selected, the TOTP can be copied from the terminal or pasted through the integrated clipboard support. TOTPs are updated automatically upon expiration. Pressing Esc will go back to the Fuzzy selection screen.

Ways to unlock the Vault

To unlock the Aegis vault, aegis-cli supports the following methods:

  1. Password prompt: If no password is provided, aegis-cli will prompt for a password.
  2. Password file: A file containing the password to unlock the Aegis vault:
  • Environment variable: AEGIS_PWFILE
  • Argument: -p <PASSWORD_FILE> or --password-file <PASSWORD_FILE>
  • Example: aegis -p ~/.aegis.pw aegis-vault.json
  1. Password: The password can be passed as an argument or set as an environment variable:
  • Environment variable: AEGIS_PASSWORD
  • Argument: -P <PASSWORD> or --password <PASSWORD>
  • Example: aegis -P jkhglhkjhkjf aegis-vault.json

Extra flags

  • -n <NAME>... or --name <NAME>...: Pre-filter entries by entries NAME.
    • Example: aegis -n git dave aegis-vault.json
  • -i <ISSUER>... or --issuer <ISSUER>...: Pre-filter entries by entries ISSUER.
  • -j or --json: Output the selected TOTPs as JSON.
  • -u or --uri: Output the selected TOTPs as otpauth URIs, according to https://datatracker.ietf.org/doc/draft-linuxgemini-otpauth-uri/01/

Help

aegis-cli 1.2.1 - Show TOTPs from Aegis vault on CLI
Usage: aegis [OPTIONS] <VAULT_FILE>
Arguments:
  <VAULT_FILE>  Encrypted Aegis Vault JSON file (separate it from name/issuer
                filters by putting -- before it [env: AEGIS_VAULT_FILE=]

Options:
  -o, --otp                  Show OTP entries in plain text
  -j, --json                 Export entries to Plain Aegis Vault JSON
  -u, --url                  Export entries in URL format
  -p, --pwfile <PWFILE>      Aegis Vault passwordfile [env: AEGIS_PWFILE=]
  -P, --password <PASSWORD>  PASSWORD for Aegis Vault [env: AEGIS_PASSWORD]
  -i, --issuer <ISSUER>...   Filter by ISSUER (multiple allowed)
  -n, --name <NAME>...       Filter by NAME (multiple allowed)
  -h, --help                 Print help
  -V, --version              Print version

Project history

This project has been divided into a CLI binary (this repo) and a vault utility crate so that other projects can utilize the parsing and TOTP generation functionalities as well.

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

Dependencies

~10–22MB
~337K SLoC