mdoc-0.3.0.0: examples/pass.1

.\" vim: ft=nroff.mustache
.Dd $Mdocdate: September 20 2026 $
.Dt PASS 1
.Os
.Sh NAME
.Nm pass
.Nd stores, retrieves, generates, and synchronizes passwords securely
.Sh SYNOPSIS
.Nm
.Bk -words
.Ar command
.Ek
.Pp
.Nm
.Cm init
.Bk -words
.Op Fl p Ar sub\-folder
.Ar gpg\-id
.Ek
.Pp
.Nm
.Cm ls
.Bk -words
.Ar subfolder
.Ek
.Pp
.Nm
.Cm grep
.Bk -words
.Op Ar GREPOPTIONS
.Ar search\-string
.Ek
.Pp
.Nm
.Cm find
.Bk -words
.Ar pass\-names
.Op Ar pass\-names ...
.Ek
.Pp
.Nm
.Cm show
.Bk -words
.Op Fl c Ar line\-number
.Op Fl q Ar line\-number
.Ar pass\-name
.Ek
.Pp
.Nm
.Cm help
.Pp
.Nm
.Cm version
.Sh DESCRIPTION
.Nm
is a very simple password store that keeps passwords inside
.Xr gpg2 1
encrypted files inside a simple directory tree residing at
.Pa ~/.password-store .
The pass utility provides a series of commands for manipulating the password
store, allowing the user to add, remove, edit, synchronize, generate, and
manipulate passwords.
.Pp
If no COMMAND is specified, COMMAND defaults to either
.Cm show
or
.Cm ls ,
depending on the type of specifier in ARGS. Alternatively, if
.Ar PASSWORD_STORE_ENABLE_EXTENSIONS
is set to "true", and the file
.Pa .extensions/COMMAND.bash
exists inside the password store and is executable, then it is sourced into the
environment, passing any arguments and environment variables. Extensions
existing in a system- wide directory, only installable by the administrator, are
always enabled.
.Pp
Otherwise COMMAND must be one of the valid commands listed below.
.Pp
Several of the commands below rely on or provide additional functionality if the
password store directory is also a git repository. If the password store
directory is a git repository, all password store modification commands will
cause a corresponding git commit. Sub- directories may be separate nested git
repositories, and pass will use the inner-most directory relative to the current
password. See the
.Ar EXTENDED GIT EXAMPLE
section for a detailed description using init and
.Xr git 1
.Pp
The
.Cm init
command must be run before other commands in order to initialize the password
store with the correct gpg key id. Passwords are encrypted using the gpg key set
with
.Cm init .
.Pp
There is a corresponding bash completion script for use with tab completing
password names in
.Xr bash 1 .
.Ss COMMANDS
.Bl -tag -width indent
.It Cm init
Initialize new password storage and use gpg\-id for encryption. Multiple
gpg\-ids may be specified, in order to encrypt each password with multiple ids.
This command must be run first before a password store can be used. If the
specified gpg\-id is different from the key used in any existing files, these
files will be reencrypted to use the new id. Note that use of gpg\-agent(1) is
recommended so that the batch decryption does not require as much user
intervention. If \-\-path or \-p is specified, along with an argument, a
specific gpg\-id or set of gpg\-ids is assigned for that specific sub folder of
the password store. If only one gpg\-id is given, and it is an empty string,
then the current .gpg\-id file for the specified sub\-folder (or root if
unspecified) is removed.
.It Cm ls
List names of passwords inside the tree at subfolder by using the tree(1)
program. This command is alternatively named list.
.It Cm grep
Searches inside each decrypted password file for search\-string, and displays
line containing matched string along with filename. Uses grep(1) for matching.
GREPOPTIONS are passed to grep(1) as\-is. (Note: the GREP_OPTIONS environment
variable functions as well.)
.It Cm find
List names of passwords inside the tree that match pass\-names by using the
tree(1) program. This command is alternatively named search.
.It Cm show
Decrypt and print a password named pass\-name. If \-\-clip or \-c is specified,
do not print the password but instead copy the first (or otherwise specified)
line to the clipboard using xclip(1) or wl\-clipboard(1) and then restore the
clipboard after 45 (or PASSWORD_STORE_CLIP_TIME) seconds. If \-\-qrcode or \-q
is specified, do not print the password but instead display a QR code using
qrencode(1) either to the terminal or graphically if supported.
.It Cm help
Show usage message.
.It Cm version
Show version information.
.El
.Sh EXIT STATUS
.Ex -std