path: root/man/pass.1

.TH PASS 1 "2012 Sept 2" ZX2C4 "Password Store"

.SH NAME
pass - stores, retrieves, generates, and synchronizes passwords securely

.SH SYNOPSIS
.B pass
[ 
.I COMMAND
] [ 
.I OPTIONS
]... [ 
.I ARGS
]...

.SH DESCRIPTION

.B pass 
is a very simple password store that keeps passwords inside 
.BR gpg (1)
encrypted files inside a simple directory tree residing at 
.IR $HOME/.password-store ,
or the environment variable \fBPASSWORD_STORE_DIR\fP if it is set.
The
.B pass
utility provides a series of commands for manipulating the password store,
allowing the user to add, remove, edit, synchronize, generate, and manipulate
passwords.

If no COMMAND is specified, COMMAND defaults to either
.B show
or
.BR ls ,
depending on the type of specifier in ARGS. Otherwise COMMAND must be one of
the valid commands listed below.

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. See the \fIEXAMPLES\fP section for an
extended description using \fBinit\fP and
.BR git (1).

The \fBinit\fP command must be run before other commands in order to initialize
the password store with the correct gpg key id.

There is a corresponding bash completion script for use with tab completing
password names in
.BR bash (1).

.SH COMMANDS

.TP
\fBinit\fP [ \fI--reencrypt\fP, \fI-e\fP ] \fIgpg-id\fP
Initialize new password storage and use
.I gpg-id
for encryption. This command must be run first before a password store can be
used. If \fI--reencrypt\fP or \fI-e\fP is specified, reencrypt all existing
passwords in the password store using \fIgpg-id\fP. Note that use of
.BR gpg-agent (1)
is recommended so that the batch decryption does not require as much user
intervention.
.TP
\fBls\fP \fIsubfolder\fP
List names of passwords inside the tree at
.I subfolder
by using the
.BR tree (1)
program. This command is alternatively named \fBlist\fP.
.TP
\fBshow\fP [ \fI--clip\fP, \fI-c\fP ] \fIpass-name\fP
Decrypt and print a password named \fIpass-name\fP. If \fI--clip\fP or \fI-c\fP
is specified, do not print the password but instead copy the first line to the
clipboard using
.BR xclip (1)
and then restore the clipboard after 45 seconds.
.TP
\fBinsert\fP [ \fI--no-echo\fP, \fI-n\fP | \fI--multiline\fP, \fI-m\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP
Insert a new password into the password store called \fIpass-name\fP. This will
read the new password from standard in. If \fI--no-echo\fP or \fI-n\fP is specified, do
disable keyboard echo when the password is entered and confirm the password by asking
for it twice. If \fI--multiline\fP or \fI-m\fP is specified, lines will be read until
EOF or Ctrl+D is reached. Otherwise, only a single line from standard in is read. Prompt
before overwriting an existing password, unless \fI--force\fP or \fI-f\fP is specified.
.TP
\fBedit\fP \fIpass-name\fP
Insert a new password or edit an existing password using the default text editor specified
by the environment variable \fBEDITOR\fP or using
.BR vi (1)
as a fallback. This mode makes use of temporary files for editing, but care is taken to
ensure that temporary files are created in \fI/dev/shm\fP in order to avoid writing to
difficult-to-erase disk sectors. If \fI/dev/shm\fP is not accessible, fallback to
the ordinary \fBTMPDIR\fP location, and print a warning.
.TP
\fBgenerate\fP [ \fI--no-symbols\fP, \fI-n\fP ] [ \fI--clip\fP, \fI-c\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name pass-length\fP
Generate a new password using
.BR pwgen (1)
of length \fIpass-length\fP and insert into \fIpass-name\fP. If \fI--no-symbols\fP or \fI-n\fP
is specified, do not use any non-alphanumeric characters in the generated password.
If \fI--clip\fP or \fI-c\fP is specified, do not print the password but instead copy
it to the clipboard using
.BR xclip (1)
and then restore the clipboard after 45 seconds. Prompt before overwriting an existing password,
unless \fI--force\fP or \fI-f\fP is specified.
.TP
\fBrm\fP [ \fI--recursive\fP, \fI-r\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP
Remove the password named \fIpass-name\fP from the password store. This command is
alternatively named \fBremove\fP or \fBdelete\fP. If \fI--recursive\fP or \fI-r\fP
is specified, delete pass-name recursively if it is a directory. If \fI--force\fP
or \fI-f\fP is specified, do not interactively prompt before removal.
.TP
\fBgit\fP \fIgit-command-args\fP...
If the password store is a git repository, pass \fIgit-command-args\fP as arguments to
.BR git (1)
using the password store as the git repository.
.TP
\fBhelp\fP
Show usage message.
.TP
\fBversion\fP
Show version information.

.SH SIMPLE EXAMPLES

.TP
Initialize password store
.B zx2c4@laptop ~ $ pass init Jason@zx2c4.com 
.br
mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019] 
.br
Password store initialized for Jason@zx2c4.com.
.TP
List existing passwords in store
.B zx2c4@laptop ~ $ pass 
.br
Password Store
.br
\[u251C]\[u2500]\[u2500] Business 
.br
\[u2502]   \[u251C]\[u2500]\[u2500] some-silly-business-site.com 
.br
\[u2502]   \[u2514]\[u2500]\[u2500] another-business-site.net 
.br
\[u251C]\[u2500]\[u2500] Email 
.br
\[u2502]   \[u251C]\[u2500]\[u2500] donenfeld.com 
.br
\[u2502]   \[u2514]\[u2500]\[u2500] zx2c4.com 
.br
\[u2514]\[u2500]\[u2500] France 
.br
    \[u251C]\[u2500]\[u2500] bank 
.br
    \[u251C]\[u2500]\[u2500] freebox 
.br
    \[u2514]\[u2500]\[u2500] mobilephone  
.br

.br
Alternatively, "\fBpass ls\fP".
.TP
Show existing password
.B zx2c4@laptop ~ $ pass Email/zx2c4.com 
.br
sup3rh4x3rizmynam3 
.TP
Copy existing password to clipboard
.B zx2c4@laptop ~ $ pass -c Email/zx2c4.com 
.br
Copied Email/jason@zx2c4.com to clipboard. Will clear in 45 seconds.
.TP
Add password to store
.B zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory 
.br
Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do
.TP
Add multiline password to store 
.B zx2c4@laptop ~ $ pass insert -m Business/cheese-whiz-factory 
.br
Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished: 
.br
 
.br
Hey this is my 
.br
awesome 
.br
multi 
.br
line 
.br
passworrrrrrrrd. 
.br
^D 
.TP
Generate new password
.B zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15 
.br
The generated password to Email/jasondonenfeld.com is: 
.br
$(-QF&Q=IN2nFBx
.TP
Generate new alphanumeric password
.B zx2c4@laptop ~ $ pass -n generate Email/jasondonenfeld.com 12
.br
The generated password to Email/jasondonenfeld.com is: 
.br
YqFsMkBeO6di
.TP
Generate new password and copy it to the clipboard
.B zx2c4@laptop ~ $ pass -c generate Email/jasondonenfeld.com 19
.br
Copied Email/jasondonenfeld.com to clipboard. Will clear in 45 seconds.
.TP
Remove password from store
.B zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory 
.br
rm: remove regular file \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]? y 
.br
removed \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]

.SH EXTENDED GIT EXAMPLE
Here, we initialize new password store, create a git repository, and then manipulate and sync passwords. Make note of the arguments to the first call of \fBpass git push\fP; consult
.BR git-push (1)
for more information.

.B zx2c4@laptop ~ $ pass init Jason@zx2c4.com 
.br
mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019] 
.br
Password store initialized for Jason@zx2c4.com. 

.B zx2c4@laptop ~ $ pass git init 
.br
Initialized empty Git repository in /home/zx2c4/.password-store/.git/
.br
[master (root-commit) 998c8fd] Added current contents of password store.
.br
 1 file changed, 1 insertion(+)
.br
 create mode 100644 .gpg-id

.B zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store 

.B zx2c4@laptop ~ $ pass generate Amazon/amazonemail@email.com 21 
.br
mkdir: created directory \[u2018]/home/zx2c4/.password-store/Amazon\[u2019] 
.br
[master 30fdc1e] Added generated password for Amazon/amazonemail@email.com to store.
.br
1 file changed, 0 insertions(+), 0 deletions(-) 
.br
create mode 100644 Amazon/amazonemail@email.com.gpg 
.br
The generated password to Amazon/amazonemail@email.com is: 
.br
<5m,_BrZY`antNDxKN<0A 

.B zx2c4@laptop ~ $ pass git push -u --all
.br
Counting objects: 4, done. 
.br
Delta compression using up to 2 threads. 
.br
Compressing objects: 100% (3/3), done. 
.br
Writing objects: 100% (4/4), 921 bytes, done. 
.br
Total 4 (delta 0), reused 0 (delta 0) 
.br
To kexec.com:pass-store 
.br
* [new branch]      master -> master 
.br
Branch master set up to track remote branch master from origin. 

.B zx2c4@laptop ~ $ pass insert Amazon/otheraccount@email.com 
.br
Enter password for Amazon/otheraccount@email.com: som3r3a11yb1gp4ssw0rd!!88** 
.br
[master b9b6746] Added given password for Amazon/otheraccount@email.com to store. 
.br
1 file changed, 0 insertions(+), 0 deletions(-) 
.br
create mode 100644 Amazon/otheraccount@email.com.gpg 

.B zx2c4@laptop ~ $ pass rm Amazon/amazonemail@email.com 
.br
rm: remove regular file \[u2018]/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg\[u2019]? y 
.br
removed \[u2018]/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg\[u2019] 
.br
rm 'Amazon/amazonemail@email.com.gpg' 
.br
[master 288b379] Removed Amazon/amazonemail@email.com from store. 
.br
1 file changed, 0 insertions(+), 0 deletions(-) 
.br
delete mode 100644 Amazon/amazonemail@email.com.gpg 

.B zx2c4@laptop ~ $ pass git push
.br
Counting objects: 9, done. 
.br
Delta compression using up to 2 threads. 
.br
Compressing objects: 100% (5/5), done. 
.br
Writing objects: 100% (7/7), 1.25 KiB, done. 
.br
Total 7 (delta 0), reused 0 (delta 0) 
.br
To kexec.com:pass-store

.SH FILES

.TP
.B ~/.password-store
The password storage directory.
.TP
.B ~/.password-store/.gpg-id
Contains the gpg key identification used for encryption and decryption. This should
be set using the \fBinit\fP command.

.SH SEE ALSO
.BR gpg (1),
.BR pwgen (1),
.BR git (1),
.BR xclip (1).

.SH AUTHOR
.B pass
was written by
.MT Jason@zx2c4.com
Jason A. Donenfeld
.ME .
For updates and more information, a project page is available on the
.UR http://\:zx2c4.com/\:projects/\:password-store
World Wide Web
.UE .

.SH COPYING
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.