% passage(1) PassAGE - A modern password manager using AGE encryption
% PassAGE developers
% 2024

# NAME

passage - A modern password manager using AGE encryption (PassAGE)

# SYNOPSIS

**passage** [*command*] [*options*] [*arguments*]

# DESCRIPTION

passage is a command-line password manager that uses AGE (Actually Good Encryption) 
for secure password storage. It uses a master password model where a single password 
protects all stored passwords.

All passwords are encrypted using AGE's Scrypt passphrase encryption and stored 
in the password store directory (default: `~/.passage-store`).

# COMMANDS

## init

**passage init** [**--path**=*subfolder*]

Initialize a new password store with a master password. Prompts for a master 
password that will be used to encrypt and decrypt all passwords.

**Options:**
- **--path**, **-p** *subfolder* - Initialize store in a subfolder

## show, ls, list

**passage** [**show**|**ls**|**list**] [*subfolder*]

Display a password or list passwords in a directory.

**Options:**
- **--clip**[=*line-number*], **-c**[=*line-number*] - Copy password (or specific line) to clipboard

## find, search

**passage find** *pass-names*...

Find passwords by name using pattern matching.

## grep

**passage grep** [*GREPOPTIONS*] *search-string*

Search for passwords containing *search-string* when decrypted.

## insert, add

**passage insert** [**--multiline**] [**--force**] *pass-name*

Insert a new password. Prompts for password input.

**Options:**
- **--multiline**, **-m** - Allow multiline input (press Ctrl+D when finished)
- **--force**, **-f** - Overwrite existing password without prompting

## edit

**passage edit** *pass-name*

Edit an existing password using the editor specified by the EDITOR environment 
variable (default: vi).

## generate

**passage generate** [**--no-symbols**] [**--clip**] [**--in-place**|**--force**] *pass-name* [*pass-length*]

Generate a new cryptographically secure random password.

**Options:**
- **--no-symbols**, **-n** - Don't include symbols in generated password
- **--clip**, **-c** - Copy generated password to clipboard
- **--in-place**, **-i** - Replace first line of existing password
- **--force**, **-f** - Overwrite existing password without prompting
- *pass-length* - Length of password to generate (default: 25)

## rm, delete, remove

**passage rm** [**--recursive**] [**--force**] *pass-name*

Remove a password or directory.

**Options:**
- **--recursive**, **-r** - Recursively remove directory
- **--force**, **-f** - Remove without prompting

## mv, rename

**passage mv** [**--force**] *old-path* *new-path*

Move or rename a password.

**Options:**
- **--force**, **-f** - Overwrite destination without prompting

## cp, copy

**passage cp** [**--force**] *old-path* *new-path*

Copy a password.

**Options:**
- **--force**, **-f** - Overwrite destination without prompting

## backup

**passage backup** [**--output**=*file.tar.gz*]

Create a backup of the password store with integrity verification.

**Options:**
- **--output**, **-o** *file.tar.gz* - Output backup file (default: passage-backup-YYYYMMDD-HHMMSS.tar.gz)

The backup includes a SHA256 checksum file for verification.

## restore

**passage restore** [**--force**] [**--skip-verify**] *backup-file.tar.gz*

Restore a backup of the password store.

**Options:**
- **--force**, **-f** - Overwrite existing store without prompting
- **--skip-verify**, **-s** - Skip checksum verification (not recommended)

## git

**passage git** *git-command-args*...

Run git commands in the password store directory. Useful for version control 
and syncing across devices.

**Examples:**
- **passage git init** - Initialize git repository
- **passage git push** - Push changes to remote
- **passage git pull** - Pull changes from remote

## help

**passage help**

Show usage information.

## version

**passage version**

Show version information.

# ENVIRONMENT VARIABLES

**PASSAGE_DIR**
  Path to the password store directory. Defaults to `~/.passage-store` if not set.

**PASSAGE_CLIP_TIME**
  Time in seconds to keep password in clipboard before auto-clearing. Defaults to 10 seconds.

**PASSAGE_GENERATED_LENGTH**
  Default length for generated passwords. Defaults to 25 if not set.

**EDITOR**
  Editor to use for the **edit** command. Defaults to `vi` if not set.

**HOME**
  Home directory path. Used as base for default store location.

**WAYLAND_DISPLAY**
  If set, indicates Wayland display is available. Used for clipboard operations.

**DISPLAY**
  If set, indicates X11 display is available. Used for clipboard operations.

# FILES

**~/.passage-store/**
  Default password store directory. Contains encrypted password files (`.passage` extension) 
  and the master password hash file (`.master-pass`).

**~/.passage-store/.master-pass**
  Stores Argon2id hash of master password for verification. Never contains the actual password.

# EXAMPLES

Initialize a new password store:

    $ passage init
    Initializing password store...
    Enter master password: 
    Confirm master password: 
    Password store initialized

Add a password:

    $ passage insert example.com
    Enter master password: 
    Enter password for example.com: 
    Password for example.com added to store.

Show a password:

    $ passage show example.com
    Enter master password: 
    mypassword123

Generate a password:

    $ passage generate example.com 32
    Enter master password: 
    The generated password for example.com is:
    xK9#mP2$vL8@nQ4&wR7!tY5*uI3^oE6

Copy password to clipboard:

    $ passage show --clip example.com
    Enter master password: 
    Copied example.com to clipboard. Will clear in 10 seconds.

Create a backup:

    $ passage backup
    Enter master password: 
    Backup created: passage-backup-20240101-120000.tar.gz
    Files backed up: 15
    Checksum: a1b2c3d4e5f6...
    Checksum file: passage-backup-20240101-120000.tar.gz.sha256

# SECURITY

PassAGE uses AGE encryption with Scrypt passphrase encryption for all password files. 
The master password is verified using Argon2id hashing, which is memory-hard and 
resistant to brute-force attacks.

**Important security notes:**

- The master password is never stored in plaintext
- All password files are encrypted individually
- File permissions are set to 0600 (files) and 0700 (directories)
- Clipboard is automatically cleared after the timeout period
- Passwords are cleared from memory when possible

For detailed security information, see **SECURITY.md** in the PassAGE source code.

# SEE ALSO

**age**(1), **git**(1)

# BUGS

Report bugs at https://git.fraggle.lol/fraggle/PassAGE/issues

# AUTHOR

PassAGE developers

# COPYRIGHT

This project uses AGE encryption. See LICENSE file for details.