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 .
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 \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.
.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 it to the clipboard
using
.BR xclip (1)
and then restore the clipboard after 45 seconds.
.TP
\fBinsert\fP [ \fI--multiline\fP, \fI-m\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--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.
.TP
\fBgenerate\fP [ \fI--no-symbols\fP, \fI-n\fP ] [ \fI--clip\fP, \fI-c\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.
.TP
\fBrm\fP \fIpass-name\fP
Remove the password named \fIpass-name\fP from the password store. This command is
alternatively named \fBremove\fP.
.TP
\fBpush\fP
If the password store is a git repository, push the latest changes using
.BR git-push (1).
.TP
\fBpull\fP
If the password store is a git repository, pull the latest changes using
.BR git-pull (1).
.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.

.SH 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]
.TP
Initialize new password store, create a git repository, and then manipulate and sync passwords
.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. 
.br
.B zx2c4@laptop ~ $ pass git init 
.br
Initialized empty Git repository in /home/zx2c4/.password-store/.git/ 
.br
.B zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store 
.br
.B zx2c4@laptop ~ $ pass generate Amazon/amazonemail@email.com 21 
.br
mkdir: created directory \[u2018]/home/zx2c4/.password-store/Amazon\[u2019] 
.br
[master (root-commit) 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 
.br
.B zx2c4@laptop ~ $ pass 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. 
.br
.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 
.br
.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 
.br
.B zx2c4@laptop ~ $ pass 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
Jason A. Donenfeld <Jason@zx2c4.com>

.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., 675 Mass Ave, Cambridge, MA 02139, USA.