1PASS(1) Password Store PASS(1)
2
6 pass - stores, retrieves, generates, and synchronizes passwords se‐
7 curely
8
11 pass [ COMMAND ] [ OPTIONS ]... [ ARGS ]...
12
15 pass is a very simple password store that keeps passwords inside
16 gpg2(1) encrypted files inside a simple directory tree residing at
17 ~/.password-store. The pass utility provides a series of commands for
18 manipulating the password store, allowing the user to add, remove,
19 edit, synchronize, generate, and manipulate passwords.
20 If no COMMAND is specified, COMMAND defaults to either show or ls, de‐
22 pending on the type of specifier in ARGS. Alternatively, if PASS‐
23 WORD_STORE_ENABLE_EXTENSIONS is set to "true", and the file .exten‐
24 sions/COMMAND.bash exists inside the password store and is executable,
25 then it is sourced into the environment, passing any arguments and en‐
26 vironment variables. Extensions existing in a system-wide directory,
27 only installable by the administrator, are always enabled.
28 Otherwise COMMAND must be one of the valid commands listed below.
30 Several of the commands below rely on or provide additional functional‐
32 ity if the password store directory is also a git repository. If the
33 password store directory is a git repository, all password store modi‐
34 fication commands will cause a corresponding git commit. Sub-directo‐
35 ries may be separate nested git repositories, and pass will use the in‐
36 ner-most directory relative to the current password. See the EXTENDED
37 GIT EXAMPLE section for a detailed description using init and git(1).
38 The init command must be run before other commands in order to initial‐
40 ize the password store with the correct gpg key id. Passwords are en‐
41 crypted using the gpg key set with init.
42 There is a corresponding bash completion script for use with tab com‐
44 pleting password names in bash(1).
45
48 init [ --path=sub-folder, -p sub-folder ] gpg-id...
49 Initialize new password storage and use gpg-id for encryption.
50 Multiple gpg-ids may be specified, in order to encrypt each
51 password with multiple ids. This command must be run first be‐
52 fore a password store can be used. If the specified gpg-id is
53 different from the key used in any existing files, these files
54 will be reencrypted to use the new id. Note that use of gpg-
55 agent(1) is recommended so that the batch decryption does not
56 require as much user intervention. If --path or -p is specified,
57 along with an argument, a specific gpg-id or set of gpg-ids is
58 assigned for that specific sub folder of the password store. If
59 only one gpg-id is given, and it is an empty string, then the
60 current .gpg-id file for the specified sub-folder (or root if
61 unspecified) is removed.
62 ls subfolder
64 List names of passwords inside the tree at subfolder by using
65 the tree(1) program. This command is alternatively named list.
66 grep [GREPOPTIONS] search-string
68 Searches inside each decrypted password file for search-string,
69 and displays line containing matched string along with filename.
70 Uses grep(1) for matching. GREPOPTIONS are passed to grep(1) as-
71 is. (Note: the GREP_OPTIONS environment variable functions as
72 well.)
73 find pass-names...
75 List names of passwords inside the tree that match pass-names by
76 using the tree(1) program. This command is alternatively named
77 search.
78 show [ --clip[=line-number], -c[line-number] ] [ --qrcode[=line-num‐
80 ber], -q[line-number] ] pass-name
81 Decrypt and print a password named pass-name. If --clip or -c is
82 specified, do not print the password but instead copy the first
83 (or otherwise specified) line to the clipboard using xclip(1) or
84 wl-clipboard(1) and then restore the clipboard after 45 (or
85 PASSWORD_STORE_CLIP_TIME) seconds. If --qrcode or -q is speci‐
86 fied, do not print the password but instead display a QR code
87 using qrencode(1) either to the terminal or graphically if sup‐
88 ported.
89 insert [ --echo, -e | --multiline, -m ] [ --force, -f ] pass-name
91 Insert a new password into the password store called pass-name.
92 This will read the new password from standard in. If --echo or
93 -e is not specified, disable keyboard echo when the password is
94 entered and confirm the password by asking for it twice. If
95 --multiline or -m is specified, lines will be read until EOF or
96 Ctrl+D is reached. Otherwise, only a single line from standard
97 in is read. Prompt before overwriting an existing password, un‐
98 less --force or -f is specified. This command is alternatively
99 named add.
100 edit pass-name
102 Insert a new password or edit an existing password using the de‐
103 fault text editor specified by the environment variable EDITOR
104 or using vi(1) as a fallback. This mode makes use of temporary
105 files for editing, but care is taken to ensure that temporary
106 files are created in /dev/shm in order to avoid writing to dif‐
107 ficult-to-erase disk sectors. If /dev/shm is not accessible,
108 fallback to the ordinary TMPDIR location, and print a warning.
109 generate [ --no-symbols, -n ] [ --clip, -c ] [ --in-place, -i |
111 --force, -f ] pass-name [pass-length]
112 Generate a new password using /dev/urandom of length pass-length
113 (or PASSWORD_STORE_GENERATED_LENGTH if unspecified) and insert
114 into pass-name. If --no-symbols or -n is specified, do not use
115 any non-alphanumeric characters in the generated password. The
116 character sets used in generating passwords can be changed with
117 the PASSWORD_STORE_CHARACTER_SET and PASSWORD_STORE_CHARAC‐
118 TER_SET_NO_SYMBOLS environment variables, described below. If
119 --clip or -c is specified, do not print the password but instead
120 copy it to the clipboard using xclip(1) or wl-clipboard(1) and
121 then restore the clipboard after 45 (or PASS‐
122 WORD_STORE_CLIP_TIME) seconds. If --qrcode or -q is specified,
123 do not print the password but instead display a QR code using
124 qrencode(1) either to the terminal or graphically if supported.
125 Prompt before overwriting an existing password, unless --force
126 or -f is specified. If --in-place or -i is specified, do not in‐
127 teractively prompt, and only replace the first line of the pass‐
128 word file with the new generated password, keeping the remainder
129 of the file intact.
130 rm [ --recursive, -r ] [ --force, -f ] pass-name
132 Remove the password named pass-name from the password store.
133 This command is alternatively named remove or delete. If --re‐
134 cursive or -r is specified, delete pass-name recursively if it
135 is a directory. If --force or -f is specified, do not interac‐
136 tively prompt before removal.
137 mv [ --force, -f ] old-path new-path
139 Renames the password or directory named old-path to new-path.
140 This command is alternatively named rename. If --force is speci‐
141 fied, silently overwrite new-path if it exists. If new-path ends
142 in a trailing /, it is always treated as a directory. Passwords
143 are selectively reencrypted to the corresponding keys of their
144 new destination.
145 cp [ --force, -f ] old-path new-path
147 Copies the password or directory named old-path to new-path.
148 This command is alternatively named copy. If --force is speci‐
149 fied, silently overwrite new-path if it exists. If new-path ends
150 in a trailing /, it is always treated as a directory. Passwords
151 are selectively reencrypted to the corresponding keys of their
152 new destination.
153 git git-command-args...
155 If the password store is a git repository, pass git-command-args
156 as arguments to git(1) using the password store as the git
157 repository. If git-command-args is init, in addition to initial‐
158 izing the git repository, add the current contents of the pass‐
159 word store to the repository in an initial commit. If the git
160 config key pass.signcommits is set to true, then all commits
161 will be signed using user.signingkey or the default git signing
162 key. This config key may be turned on using: `pass git config
163 --bool --add pass.signcommits true`
164 help Show usage message.
166 version
168 Show version information.
169
172 Initialize password store
173 zx2c4@laptop ~ $ pass init Jason@zx2c4.com
174 mkdir: created directory ‘/home/zx2c4/.password-store’
175 Password store initialized for Jason@zx2c4.com.
176 List existing passwords in store
178 zx2c4@laptop ~ $ pass
179 Password Store
180 ├── Business
181 │ ├── some-silly-business-site.com
182 │ └── another-business-site.net
183 ├── Email
184 │ ├── donenfeld.com
185 │ └── zx2c4.com
186 └── France
187 ├── bank
188 ├── freebox
189 └── mobilephone
190 Alternatively, "pass ls".
192 Find existing passwords in store that match .com
194 zx2c4@laptop ~ $ pass find .com
195 Search Terms: .com
196 ├── Business
197 │ ├── some-silly-business-site.com
198 └── Email
199 ├── donenfeld.com
200 └── zx2c4.com
201 Alternatively, "pass search .com".
203 Show existing password
205 zx2c4@laptop ~ $ pass Email/zx2c4.com
206 sup3rh4x3rizmynam3
207 Copy existing password to clipboard
209 zx2c4@laptop ~ $ pass -c Email/zx2c4.com
210 Copied Email/jason@zx2c4.com to clipboard. Will clear in 45 sec‐
211 onds.
212 Add password to store
214 zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory
215 Enter password for Business/cheese-whiz-factory: omg so much
216 cheese what am i gonna do
217 Add multiline password to store
219 zx2c4@laptop ~ $ pass insert -m Business/cheese-whiz-factory
220 Enter contents of Business/cheese-whiz-factory and press Ctrl+D
221 when finished:
222 Hey this is my
224 awesome
225 multi
226 line
227 passworrrrrrrrd.
228 ^D
229 Generate new password
231 zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15
232 The generated password to Email/jasondonenfeld.com is:
233 $(-QF&Q=IN2nFBx
234 Generate new alphanumeric password
236 zx2c4@laptop ~ $ pass generate -n Email/jasondonenfeld.com 12
237 The generated password to Email/jasondonenfeld.com is:
238 YqFsMkBeO6di
239 Generate new password and copy it to the clipboard
241 zx2c4@laptop ~ $ pass generate -c Email/jasondonenfeld.com 19
242 Copied Email/jasondonenfeld.com to clipboard. Will clear in 45
243 seconds.
244 Remove password from store
246 zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory
247 rm: remove regular file ‘/home/zx2c4/.password-store/Busi‐
248 ness/cheese-whiz-factory.gpg’? y
249 removed ‘/home/zx2c4/.password-store/Business/cheese-whiz-fac‐
250 tory.gpg’
251
254 Here, we initialize new password store, create a git repository, and
255 then manipulate and sync passwords. Make note of the arguments to the
256 first call of pass git push; consult git-push(1) for more information.
257 zx2c4@laptop ~ $ pass init Jason@zx2c4.com
259 mkdir: created directory ‘/home/zx2c4/.password-store’
260 Password store initialized for Jason@zx2c4.com.
261 zx2c4@laptop ~ $ pass git init
263 Initialized empty Git repository in /home/zx2c4/.password-store/.git/
264 [master (root-commit) 998c8fd] Added current contents of password
265 store.
266 1 file changed, 1 insertion(+)
267 create mode 100644 .gpg-id
268 zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store
270 zx2c4@laptop ~ $ pass generate Amazon/amazonemail@email.com 21
272 mkdir: created directory ‘/home/zx2c4/.password-store/Amazon’
273 [master 30fdc1e] Added generated password for Amazon/amazone‐
274 mail@email.com to store.
275 1 file changed, 0 insertions(+), 0 deletions(-)
276 create mode 100644 Amazon/amazonemail@email.com.gpg
277 The generated password to Amazon/amazonemail@email.com is:
278 <5m,_BrZY`antNDxKN<0A
279 zx2c4@laptop ~ $ pass git push -u --all
281 Counting objects: 4, done.
282 Delta compression using up to 2 threads.
283 Compressing objects: 100% (3/3), done.
284 Writing objects: 100% (4/4), 921 bytes, done.
285 Total 4 (delta 0), reused 0 (delta 0)
286 To kexec.com:pass-store
287 * [new branch] master -> master
288 Branch master set up to track remote branch master from origin.
289 zx2c4@laptop ~ $ pass insert Amazon/otheraccount@email.com
291 Enter password for Amazon/otheraccount@email.com:
292 som3r3a11yb1gp4ssw0rd!!88**
293 [master b9b6746] Added given password for Amazon/otheraccount@email.com
294 to store.
295 1 file changed, 0 insertions(+), 0 deletions(-)
296 create mode 100644 Amazon/otheraccount@email.com.gpg
297 zx2c4@laptop ~ $ pass rm Amazon/amazonemail@email.com
299 rm: remove regular file ‘/home/zx2c4/.password-store/Amazon/amazone‐
300 mail@email.com.gpg’? y
301 removed ‘/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg’
302 rm 'Amazon/amazonemail@email.com.gpg'
303 [master 288b379] Removed Amazon/amazonemail@email.com from store.
304 1 file changed, 0 insertions(+), 0 deletions(-)
305 delete mode 100644 Amazon/amazonemail@email.com.gpg
306 zx2c4@laptop ~ $ pass git push
308 Counting objects: 9, done.
309 Delta compression using up to 2 threads.
310 Compressing objects: 100% (5/5), done.
311 Writing objects: 100% (7/7), 1.25 KiB, done.
312 Total 7 (delta 0), reused 0 (delta 0)
313 To kexec.com:pass-store
314
317 ~/.password-store
318 The default password storage directory.
319 ~/.password-store/.gpg-id
321 Contains the default gpg key identification used for encryption
322 and decryption. Multiple gpg keys may be specified in this
323 file, one per line. If this file exists in any sub directories,
324 passwords inside those sub directories are encrypted using those
325 keys. This should be set using the init command.
326 ~/.password-store/.extensions
328 The directory containing extension files.
329
332 PASSWORD_STORE_DIR
333 Overrides the default password storage directory.
334 PASSWORD_STORE_KEY
336 Overrides the default gpg key identification set by init. Keys
337 must not contain spaces and thus use of the hexadecimal key sig‐
338 nature is recommended. Multiple keys may be specified separated
339 by spaces.
340 PASSWORD_STORE_GPG_OPTS
342 Additional options to be passed to all invocations of GPG.
343 PASSWORD_STORE_X_SELECTION
345 Overrides the selection passed to xclip, by default clipboard.
346 See xclip(1) for more info.
347 PASSWORD_STORE_CLIP_TIME
349 Specifies the number of seconds to wait before restoring the
350 clipboard, by default 45 seconds.
351 PASSWORD_STORE_UMASK
353 Sets the umask of all files modified by pass, by default 077.
354 PASSWORD_STORE_GENERATED_LENGTH
356 The default password length if the pass-length parameter to gen‐
357 erate is unspecified.
358 PASSWORD_STORE_CHARACTER_SET
360 The character set to be used in password generation for gener‐
361 ate. This value is to be interpreted by tr. See tr(1) for more
362 info.
363 PASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS
365 The character set to be used in no-symbol password generation
366 for generate, when --no-symbols, -n is specified. This value is
367 to be interpreted by tr. See tr(1) for more info.
368 PASSWORD_STORE_ENABLE_EXTENSIONS
370 This environment variable must be set to "true" for extensions
371 to be enabled.
372 PASSWORD_STORE_EXTENSIONS_DIR
374 The location to look for executable extension files, by default
375 PASSWORD_STORE_DIR/.extensions.
376 PASSWORD_STORE_SIGNING_KEY
378 If this environment variable is set, then all .gpg-id files and
379 non-system extension files must be signed using a detached sig‐
380 nature using the GPG key specified by the full 40 character up‐
381 per-case fingerprint in this variable. If multiple fingerprints
382 are specified, each separated by a whitespace character, then
383 signatures must match at least one. The init command will keep
384 signatures of .gpg-id files up to date.
385 EDITOR The location of the text editor used by edit.
387
389 gpg2(1), tr(1), git(1), xclip(1), wl-clipboard(1), qrencode(1).
390
393 pass was written by Jason A. Donenfeld ⟨Jason@zx2c4.com⟩. For updates
394 and more information, a project page is available on the World Wide Web
395 ⟨http://www.passwordstore.org/⟩.
396
399 This program is free software; you can redistribute it and/or modify it
400 under the terms of the GNU General Public License as published by the
401 Free Software Foundation; either version 2 of the License, or (at your
402 option) any later version.
403 This program is distributed in the hope that it will be useful, but
405 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
406 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
407 Public License for more details.
408 You should have received a copy of the GNU General Public License along
410 with this program; if not, write to the Free Software Foundation, Inc.,
411 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
412ZX2C4 2014 March 18 PASS(1)