1 .TH PASS 1 "2014 March 18" ZX2C4 "Password Store"
4 pass - stores, retrieves, generates, and synchronizes passwords securely
19 is a very simple password store that keeps passwords inside
21 encrypted files inside a simple directory tree residing at
22 .IR ~/.password-store .
25 utility provides a series of commands for manipulating the password store,
26 allowing the user to add, remove, edit, synchronize, generate, and manipulate
29 If no COMMAND is specified, COMMAND defaults to either
33 depending on the type of specifier in ARGS. Otherwise COMMAND must be one of
34 the valid commands listed below.
36 Several of the commands below rely on or provide additional functionality if
37 the password store directory is also a git repository. If the password store
38 directory is a git repository, all password store modification commands will
39 cause a corresponding git commit. See the \fIEXTENDED GIT EXAMPLE\fP section
40 for a detailed description using \fBinit\fP and
43 The \fBinit\fP command must be run before other commands in order to initialize
44 the password store with the correct gpg key id. Passwords are encrypting using
45 the gpg key set with \fBinit\fP.
47 There is a corresponding bash completion script for use with tab completing
54 \fBinit\fP [ \fI--path=sub-folder\fP, \fI-p sub-folder\fP ] \fIgpg-id...\fP
55 Initialize new password storage and use
57 for encryption. Multiple gpg-ids may be specified, in order to encrypt each
58 password with multiple ids. This command must be run first before a password
59 store can be used. If the specified \fIgpg-id\fP is different from the key
60 used in any existing files, these files will be reencrypted to use the new id.
63 is recommended so that the batch decryption does not require as much user
64 intervention. If \fI--path\fP or \fI-p\fP is specified, along with an argument,
65 a specific gpg-id or set of gpg-ids is assigned for that specific sub folder of
66 the password store. If only one \fIgpg-id\fP is given, and it is an empty string,
67 then the current \fI.gpg-id\fP file for the specified \fIsub-folder\fP (or root if
68 unspecified) is removed.
70 \fBls\fP \fIsubfolder\fP
71 List names of passwords inside the tree at
75 program. This command is alternatively named \fBlist\fP.
77 \fBgrep\fP \fIsearch-string\fP
78 Searches inside each decrypted password file for \fIsearch-string\fP, and displays line
79 containing matched string along with filename. Uses
81 for matching. Make use of the \fIGREP_OPTIONS\fP environment variable to set particular
84 \fBfind\fP \fIpass-names\fP...
85 List names of passwords inside the tree that match \fIpass-names\fP by using the
87 program. This command is alternatively named \fBsearch\fP.
89 \fBshow\fP [ \fI--clip\fP, \fI-c\fP ] \fIpass-name\fP
90 Decrypt and print a password named \fIpass-name\fP. If \fI--clip\fP or \fI-c\fP
91 is specified, do not print the password but instead copy the first line to the
94 and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds.
96 \fBinsert\fP [ \fI--echo\fP, \fI-e\fP | \fI--multiline\fP, \fI-m\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP
97 Insert a new password into the password store called \fIpass-name\fP. This will
98 read the new password from standard in. If \fI--echo\fP or \fI-e\fP is \fInot\fP specified,
99 disable keyboard echo when the password is entered and confirm the password by asking
100 for it twice. If \fI--multiline\fP or \fI-m\fP is specified, lines will be read until
101 EOF or Ctrl+D is reached. Otherwise, only a single line from standard in is read. Prompt
102 before overwriting an existing password, unless \fI--force\fP or \fI-f\fP is specified. This
103 command is alternatively named \fBadd\fP.
105 \fBedit\fP \fIpass-name\fP
106 Insert a new password or edit an existing password using the default text editor specified
107 by the environment variable \fIEDITOR\fP or using
109 as a fallback. This mode makes use of temporary files for editing, but care is taken to
110 ensure that temporary files are created in \fI/dev/shm\fP in order to avoid writing to
111 difficult-to-erase disk sectors. If \fI/dev/shm\fP is not accessible, fallback to
112 the ordinary \fITMPDIR\fP location, and print a warning.
114 \fBgenerate\fP [ \fI--no-symbols\fP, \fI-n\fP ] [ \fI--clip\fP, \fI-c\fP ] [ \fI--in-place\fP, \fI-i\fP | \fI--force\fP, \fI-f\fP ] \fIpass-name pass-length\fP
115 Generate a new password using
117 of length \fIpass-length\fP and insert into \fIpass-name\fP. If \fI--no-symbols\fP or \fI-n\fP
118 is specified, do not use any non-alphanumeric characters in the generated password.
119 If \fI--clip\fP or \fI-c\fP is specified, do not print the password but instead copy
120 it to the clipboard using
122 and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds.
123 Prompt before overwriting an existing password,
124 unless \fI--force\fP or \fI-f\fP is specified. If \fI--in-place\fP or \fI-i\fP is
125 specified, do not interactively prompt, and only replace the first line of the password
126 file with the new generated password, keeping the remainder of the file intact.
128 \fBrm\fP [ \fI--recursive\fP, \fI-r\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP
129 Remove the password named \fIpass-name\fP from the password store. This command is
130 alternatively named \fBremove\fP or \fBdelete\fP. If \fI--recursive\fP or \fI-r\fP
131 is specified, delete pass-name recursively if it is a directory. If \fI--force\fP
132 or \fI-f\fP is specified, do not interactively prompt before removal.
134 \fBmv\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP
135 Renames the password or directory named \fIold-path\fP to \fInew-path\fP. This
136 command is alternatively named \fBrename\fP. If \fI--force\fP is specified,
137 silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a
138 trailing \fI/\fP, it is always treated as a directory. Passwords are selectively
139 reencrypted to the corresponding keys of their new destination.
141 \fBcp\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP
142 Copies the password or directory named \fIold-path\fP to \fInew-path\fP. This
143 command is alternatively named \fBcopy\fP. If \fI--force\fP is specified,
144 silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a
145 trailing \fI/\fP, it is always treated as a directory. Passwords are selectively
146 reencrypted to the corresponding keys of their new destination.
148 \fBgit\fP \fIgit-command-args\fP...
149 If the password store is a git repository, pass \fIgit-command-args\fP as arguments to
151 using the password store as the git repository. If \fIgit-command-args\fP is \fBinit\fP,
152 in addition to initializing the git repository, add the current contents of the password
153 store to the repository in an initial commit. If the git config key \fIpass.signcommits\fP
154 is set to \fItrue\fP, then all commits will be signed using \fIuser.signingkey\fP or the
155 default git signing key. This config key may be turned on using:
156 .B `pass git config --bool --add pass.signcommits true`
162 Show version information.
167 Initialize password store
170 mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019]
174 List existing passwords in store
175 .B zx2c4@laptop ~ $ pass
179 \[u251C]\[u2500]\[u2500] Business
181 \[u2502] \[u251C]\[u2500]\[u2500] some-silly-business-site.com
183 \[u2502] \[u2514]\[u2500]\[u2500] another-business-site.net
185 \[u251C]\[u2500]\[u2500] Email
187 \[u2502] \[u251C]\[u2500]\[u2500] donenfeld.com
189 \[u2502] \[u2514]\[u2500]\[u2500] zx2c4.com
191 \[u2514]\[u2500]\[u2500] France
193 \[u251C]\[u2500]\[u2500] bank
195 \[u251C]\[u2500]\[u2500] freebox
197 \[u2514]\[u2500]\[u2500] mobilephone
201 Alternatively, "\fBpass ls\fP".
203 Find existing passwords in store that match .com
204 .B zx2c4@laptop ~ $ pass find .com
208 \[u251C]\[u2500]\[u2500] Business
210 \[u2502] \[u251C]\[u2500]\[u2500] some-silly-business-site.com
212 \[u2514]\[u2500]\[u2500] Email
214 \[u251C]\[u2500]\[u2500] donenfeld.com
216 \[u2514]\[u2500]\[u2500] zx2c4.com
220 Alternatively, "\fBpass search .com\fP".
222 Show existing password
223 .B zx2c4@laptop ~ $ pass Email/zx2c4.com
227 Copy existing password to clipboard
228 .B zx2c4@laptop ~ $ pass -c Email/zx2c4.com
232 Add password to store
233 .B zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory
235 Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do
237 Add multiline password to store
238 .B zx2c4@laptop ~ $ pass insert -m Business/cheese-whiz-factory
240 Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished:
256 Generate new password
257 .B zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15
259 The generated password to Email/jasondonenfeld.com is:
263 Generate new alphanumeric password
264 .B zx2c4@laptop ~ $ pass generate -n Email/jasondonenfeld.com 12
266 The generated password to Email/jasondonenfeld.com is:
270 Generate new password and copy it to the clipboard
271 .B zx2c4@laptop ~ $ pass generate -c Email/jasondonenfeld.com 19
273 Copied Email/jasondonenfeld.com to clipboard. Will clear in 45 seconds.
275 Remove password from store
276 .B zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory
278 rm: remove regular file \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]? y
280 removed \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]
282 .SH EXTENDED GIT EXAMPLE
283 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
285 for more information.
289 mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019]
293 .B zx2c4@laptop ~ $ pass git init
295 Initialized empty Git repository in /home/zx2c4/.password-store/.git/
297 [master (root-commit) 998c8fd] Added current contents of password store.
299 1 file changed, 1 insertion(+)
301 create mode 100644 .gpg-id
303 .B zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store
307 mkdir: created directory \[u2018]/home/zx2c4/.password-store/Amazon\[u2019]
311 1 file changed, 0 insertions(+), 0 deletions(-)
317 <5m,_BrZY`antNDxKN<0A
319 .B zx2c4@laptop ~ $ pass git push -u --all
321 Counting objects: 4, done.
323 Delta compression using up to 2 threads.
325 Compressing objects: 100% (3/3), done.
327 Writing objects: 100% (4/4), 921 bytes, done.
329 Total 4 (delta 0), reused 0 (delta 0)
331 To kexec.com:pass-store
333 * [new branch] master -> master
335 Branch master set up to track remote branch master from origin.
343 1 file changed, 0 insertions(+), 0 deletions(-)
357 1 file changed, 0 insertions(+), 0 deletions(-)
361 .B zx2c4@laptop ~ $ pass git push
363 Counting objects: 9, done.
365 Delta compression using up to 2 threads.
367 Compressing objects: 100% (5/5), done.
369 Writing objects: 100% (7/7), 1.25 KiB, done.
371 Total 7 (delta 0), reused 0 (delta 0)
373 To kexec.com:pass-store
379 The default password storage directory.
381 .B ~/.password-store/.gpg-id
382 Contains the default gpg key identification used for encryption and decryption.
383 Multiple gpg keys may be specified in this file, one per line. If this file
384 exists in any sub directories, passwords inside those sub directories are
385 encrypted using those keys. This should be set using the \fBinit\fP command.
387 .SH ENVIRONMENT VARIABLES
390 .I PASSWORD_STORE_DIR
391 Overrides the default password storage directory.
393 .I PASSWORD_STORE_KEY
394 Overrides the default gpg key identification set by \fBinit\fP. Keys must not
395 contain spaces and thus use of the hexidecimal key signature is recommended.
396 Multiple keys may be specified separated by spaces.
398 .I PASSWORD_STORE_GIT
399 Overrides the default root of the git repository, which is helpful if
400 \fIPASSWORD_STORE_DIR\fP is temporarily set to a sub-directory of the default
403 .I PASSWORD_STORE_GPG_OPTS
404 Additional options to be passed to all invocations of GPG.
406 .I PASSWORD_STORE_X_SELECTION
407 Overrides the selection passed to \fBxclip\fP, by default \fIclipboard\fP. See
411 .I PASSWORD_STORE_CLIP_TIME
412 Specifies the number of seconds to wait before restoring the clipboard, by default
415 .I PASSWORD_STORE_UMASK
416 Sets the umask of all files modified by pass, by default \fI077\fP.
419 The location of the text editor used by \fBedit\fP.
432 For updates and more information, a project page is available on the
433 .UR http://\:www.passwordstore.org/
438 This program is free software; you can redistribute it and/or
439 modify it under the terms of the GNU General Public License
440 as published by the Free Software Foundation; either version 2
441 of the License, or (at your option) any later version.
443 This program is distributed in the hope that it will be useful,
444 but WITHOUT ANY WARRANTY; without even the implied warranty of
445 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
446 GNU General Public License for more details.
448 You should have received a copy of the GNU General Public License
449 along with this program; if not, write to the Free Software
450 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.