1PASS(1) Password Store PASS(1)
2
6 pass - stores, retrieves, generates, and synchronizes passwords
7 securely
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,
22 depending 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
26 environment 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
36 inner-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
41 encrypted 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
52 before 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)
84 and then restore the clipboard after 45 (or PASS‐
85 WORD_STORE_CLIP_TIME) seconds. If --qrcode or -q is specified,
86 do not print the password but instead display a QR code using
87 qrencode(1) either to the terminal or graphically if supported.
88 insert [ --echo, -e | --multiline, -m ] [ --force, -f ] pass-name
90 Insert a new password into the password store called pass-name.
91 This will read the new password from standard in. If --echo or
92 -e is not specified, disable keyboard echo when the password is
93 entered and confirm the password by asking for it twice. If
94 --multiline or -m is specified, lines will be read until EOF or
95 Ctrl+D is reached. Otherwise, only a single line from standard
96 in is read. Prompt before overwriting an existing password,
97 unless --force or -f is specified. This command is alternatively
98 named add.
99 edit pass-name
101 Insert a new password or edit an existing password using the
102 default text editor specified by the environment variable EDITOR
103 or using vi(1) as a fallback. This mode makes use of temporary
104 files for editing, but care is taken to ensure that temporary
105 files are created in /dev/shm in order to avoid writing to dif‐
106 ficult-to-erase disk sectors. If /dev/shm is not accessible,
107 fallback to the ordinary TMPDIR location, and print a warning.
108 generate [ --no-symbols, -n ] [ --clip, -c ] [ --in-place, -i |
110 --force, -f ] pass-name [pass-length]
111 Generate a new password using /dev/urandom of length pass-length
112 (or PASSWORD_STORE_GENERATED_LENGTH if unspecified) and insert
113 into pass-name. If --no-symbols or -n is specified, do not use
114 any non-alphanumeric characters in the generated password. The
115 character sets used in generating passwords can be changed with
116 the PASSWORD_STORE_CHARACTER_SET and PASSWORD_STORE_CHARAC‐
117 TER_SET_NO_SYMBOLS environment variables, described below. If
118 --clip or -c is specified, do not print the password but instead
119 copy it to the clipboard using xclip(1) and then restore the
120 clipboard after 45 (or PASSWORD_STORE_CLIP_TIME) seconds. If
121 --qrcode or -q is specified, do not print the password but
122 instead display a QR code using qrencode(1) either to the termi‐
123 nal or graphically if supported. Prompt before overwriting an
124 existing password, unless --force or -f is specified. If --in-
125 place or -i is specified, do not interactively prompt, and only
126 replace the first line of the password file with the new gener‐
127 ated password, keeping the remainder of the file intact.
128 rm [ --recursive, -r ] [ --force, -f ] pass-name
130 Remove the password named pass-name from the password store.
131 This command is alternatively named remove or delete. If
132 --recursive or -r is specified, delete pass-name recursively if
133 it is a directory. If --force or -f is specified, do not inter‐
134 actively prompt before removal.
135 mv [ --force, -f ] old-path new-path
137 Renames the password or directory named old-path to new-path.
138 This command is alternatively named rename. If --force is speci‐
139 fied, silently overwrite new-path if it exists. If new-path ends
140 in a trailing /, it is always treated as a directory. Passwords
141 are selectively reencrypted to the corresponding keys of their
142 new destination.
143 cp [ --force, -f ] old-path new-path
145 Copies the password or directory named old-path to new-path.
146 This command is alternatively named copy. If --force is speci‐
147 fied, silently overwrite new-path if it exists. If new-path ends
148 in a trailing /, it is always treated as a directory. Passwords
149 are selectively reencrypted to the corresponding keys of their
150 new destination.
151 git git-command-args...
153 If the password store is a git repository, pass git-command-args
154 as arguments to git(1) using the password store as the git
155 repository. If git-command-args is init, in addition to initial‐
156 izing the git repository, add the current contents of the pass‐
157 word store to the repository in an initial commit. If the git
158 config key pass.signcommits is set to true, then all commits
159 will be signed using user.signingkey or the default git signing
160 key. This config key may be turned on using: `pass git config
161 --bool --add pass.signcommits true`
162 help Show usage message.
164 version
166 Show version information.
167
170 Initialize password store
171 zx2c4@laptop ~ $ pass init Jason@zx2c4.com
172 mkdir: created directory ‘/home/zx2c4/.password-store’
173 Password store initialized for Jason@zx2c4.com.
174 List existing passwords in store
176 zx2c4@laptop ~ $ pass
177 Password Store
178 ├── Business
179 │ ├── some-silly-business-site.com
180 │ └── another-business-site.net
181 ├── Email
182 │ ├── donenfeld.com
183 │ └── zx2c4.com
184 └── France
185 ├── bank
186 ├── freebox
187 └── mobilephone
188 Alternatively, "pass ls".
190 Find existing passwords in store that match .com
192 zx2c4@laptop ~ $ pass find .com
193 Search Terms: .com
194 ├── Business
195 │ ├── some-silly-business-site.com
196 └── Email
197 ├── donenfeld.com
198 └── zx2c4.com
199 Alternatively, "pass search .com".
201 Show existing password
203 zx2c4@laptop ~ $ pass Email/zx2c4.com
204 sup3rh4x3rizmynam3
205 Copy existing password to clipboard
207 zx2c4@laptop ~ $ pass -c Email/zx2c4.com
208 Copied Email/jason@zx2c4.com to clipboard. Will clear in 45 sec‐
209 onds.
210 Add password to store
212 zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory
213 Enter password for Business/cheese-whiz-factory: omg so much
214 cheese what am i gonna do
215 Add multiline password to store
217 zx2c4@laptop ~ $ pass insert -m Business/cheese-whiz-factory
218 Enter contents of Business/cheese-whiz-factory and press Ctrl+D
219 when finished:
220 Hey this is my
222 awesome
223 multi
224 line
225 passworrrrrrrrd.
226 ^D
227 Generate new password
229 zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15
230 The generated password to Email/jasondonenfeld.com is:
231 $(-QF&Q=IN2nFBx
232 Generate new alphanumeric password
234 zx2c4@laptop ~ $ pass generate -n Email/jasondonenfeld.com 12
235 The generated password to Email/jasondonenfeld.com is:
236 YqFsMkBeO6di
237 Generate new password and copy it to the clipboard
239 zx2c4@laptop ~ $ pass generate -c Email/jasondonenfeld.com 19
240 Copied Email/jasondonenfeld.com to clipboard. Will clear in 45
241 seconds.
242 Remove password from store
244 zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory
245 rm: remove regular file ‘/home/zx2c4/.password-store/Busi‐
246 ness/cheese-whiz-factory.gpg’? y
247 removed ‘/home/zx2c4/.password-store/Business/cheese-whiz-fac‐
248 tory.gpg’
249
252 Here, we initialize new password store, create a git repository, and
253 then manipulate and sync passwords. Make note of the arguments to the
254 first call of pass git push; consult git-push(1) for more information.
255 zx2c4@laptop ~ $ pass init Jason@zx2c4.com
257 mkdir: created directory ‘/home/zx2c4/.password-store’
258 Password store initialized for Jason@zx2c4.com.
259 zx2c4@laptop ~ $ pass git init
261 Initialized empty Git repository in /home/zx2c4/.password-store/.git/
262 [master (root-commit) 998c8fd] Added current contents of password
263 store.
264 1 file changed, 1 insertion(+)
265 create mode 100644 .gpg-id
266 zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store
268 zx2c4@laptop ~ $ pass generate Amazon/amazonemail@email.com 21
270 mkdir: created directory ‘/home/zx2c4/.password-store/Amazon’
271 [master 30fdc1e] Added generated password for Amazon/amazone‐
272 mail@email.com to store.
273 1 file changed, 0 insertions(+), 0 deletions(-)
274 create mode 100644 Amazon/amazonemail@email.com.gpg
275 The generated password to Amazon/amazonemail@email.com is:
276 <5m,_BrZY`antNDxKN<0A
277 zx2c4@laptop ~ $ pass git push -u --all
279 Counting objects: 4, done.
280 Delta compression using up to 2 threads.
281 Compressing objects: 100% (3/3), done.
282 Writing objects: 100% (4/4), 921 bytes, done.
283 Total 4 (delta 0), reused 0 (delta 0)
284 To kexec.com:pass-store
285 * [new branch] master -> master
286 Branch master set up to track remote branch master from origin.
287 zx2c4@laptop ~ $ pass insert Amazon/otheraccount@email.com
289 Enter password for Amazon/otheraccount@email.com:
290 som3r3a11yb1gp4ssw0rd!!88**
291 [master b9b6746] Added given password for Amazon/otheraccount@email.com
292 to store.
293 1 file changed, 0 insertions(+), 0 deletions(-)
294 create mode 100644 Amazon/otheraccount@email.com.gpg
295 zx2c4@laptop ~ $ pass rm Amazon/amazonemail@email.com
297 rm: remove regular file ‘/home/zx2c4/.password-store/Amazon/amazone‐
298 mail@email.com.gpg’? y
299 removed ‘/home/zx2c4/.password-store/Amazon/amazonemail@email.com.gpg’
300 rm 'Amazon/amazonemail@email.com.gpg'
301 [master 288b379] Removed Amazon/amazonemail@email.com from store.
302 1 file changed, 0 insertions(+), 0 deletions(-)
303 delete mode 100644 Amazon/amazonemail@email.com.gpg
304 zx2c4@laptop ~ $ pass git push
306 Counting objects: 9, done.
307 Delta compression using up to 2 threads.
308 Compressing objects: 100% (5/5), done.
309 Writing objects: 100% (7/7), 1.25 KiB, done.
310 Total 7 (delta 0), reused 0 (delta 0)
311 To kexec.com:pass-store
312
315 ~/.password-store
316 The default password storage directory.
317 ~/.password-store/.gpg-id
319 Contains the default gpg key identification used for encryption
320 and decryption. Multiple gpg keys may be specified in this
321 file, one per line. If this file exists in any sub directories,
322 passwords inside those sub directories are encrypted using those
323 keys. This should be set using the init command.
324 ~/.password-store/.extensions
326 The directory containing extension files.
327
330 PASSWORD_STORE_DIR
331 Overrides the default password storage directory.
332 PASSWORD_STORE_KEY
334 Overrides the default gpg key identification set by init. Keys
335 must not contain spaces and thus use of the hexadecimal key sig‐
336 nature is recommended. Multiple keys may be specified separated
337 by spaces.
338 PASSWORD_STORE_GPG_OPTS
340 Additional options to be passed to all invocations of GPG.
341 PASSWORD_STORE_X_SELECTION
343 Overrides the selection passed to xclip, by default clipboard.
344 See xclip(1) for more info.
345 PASSWORD_STORE_CLIP_TIME
347 Specifies the number of seconds to wait before restoring the
348 clipboard, by default 45 seconds.
349 PASSWORD_STORE_UMASK
351 Sets the umask of all files modified by pass, by default 077.
352 PASSWORD_STORE_GENERATED_LENGTH
354 The default password length if the pass-length parameter to gen‐
355 erate is unspecified.
356 PASSWORD_STORE_CHARACTER_SET
358 The character set to be used in password generation for gener‐
359 ate. This value is to be interpreted by tr. See tr(1) for more
360 info.
361 PASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS
363 The character set to be used in no-symbol password generation
364 for generate, when --no-symbols, -n is specified. This value is
365 to be interpreted by tr. See tr(1) for more info.
366 PASSWORD_STORE_ENABLE_EXTENSIONS
368 This environment variable must be set to "true" for extensions
369 to be enabled.
370 PASSWORD_STORE_EXTENSIONS_DIR
372 The location to look for executable extension files, by default
373 PASSWORD_STORE_DIR/.extensions.
374 PASSWORD_STORE_SIGNING_KEY
376 If this environment variable is set, then all .gpg-id files and
377 non-system extension files must be signed using a detached sig‐
378 nature using the GPG key specified by the full 40 character
379 upper-case fingerprint in this variable. If multiple finger‐
380 prints are specified, each separated by a whitespace character,
381 then signatures must match at least one. The init command will
382 keep signatures of .gpg-id files up to date.
383 EDITOR The location of the text editor used by edit.
385
387 gpg2(1), tr(1), git(1), xclip(1), qrencode(1).
388
391 pass was written by Jason A. Donenfeld ⟨Jason@zx2c4.com⟩. For updates
392 and more information, a project page is available on the World Wide Web
393 ⟨http://www.passwordstore.org/⟩.
394
397 This program is free software; you can redistribute it and/or modify it
398 under the terms of the GNU General Public License as published by the
399 Free Software Foundation; either version 2 of the License, or (at your
400 option) any later version.
401 This program is distributed in the hope that it will be useful, but
403 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
404 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
405 Public License for more details.
406 You should have received a copy of the GNU General Public License along
408 with this program; if not, write to the Free Software Foundation, Inc.,
409 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
410ZX2C4 2014 March 18 PASS(1)