1PASS(1)                         Password Store                         PASS(1)
2
3
4

NAME

6       pass  -  stores,  retrieves,  generates, and synchronizes passwords se‐
7       curely
8
9

SYNOPSIS

11       pass [ COMMAND ] [ OPTIONS ]... [ ARGS ]...
12
13

DESCRIPTION

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
21       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
29       Otherwise COMMAND must be one of the valid commands listed below.
30
31       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
39       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
43       There is a corresponding bash completion script for use with  tab  com‐
44       pleting password names in bash(1).
45
46

COMMANDS

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
63       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
67       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
74       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
79       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
90       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
101       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
110       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
131       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
138       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
146       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
154       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
165       help   Show usage message.
166
167       version
168              Show version information.
169
170

SIMPLE EXAMPLES

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
177       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
191              Alternatively, "pass ls".
192
193       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
202              Alternatively, "pass search .com".
203
204       Show existing password
205              zx2c4@laptop ~ $ pass Email/zx2c4.com
206              sup3rh4x3rizmynam3
207
208       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
213       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
218       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
223              Hey this is my
224              awesome
225              multi
226              line
227              passworrrrrrrrd.
228              ^D
229
230       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
235       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
240       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
245       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
252

EXTENDED GIT EXAMPLE

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
258       zx2c4@laptop ~ $ pass init Jason@zx2c4.com
259       mkdir: created directory ‘/home/zx2c4/.password-store’
260       Password store initialized for Jason@zx2c4.com.
261
262       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
269       zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store
270
271       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
280       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
290       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
298       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
307       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
315

FILES

317       ~/.password-store
318              The default password storage directory.
319
320       ~/.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
327       ~/.password-store/.extensions
328              The directory containing extension files.
329
330

ENVIRONMENT VARIABLES

332       PASSWORD_STORE_DIR
333              Overrides the default password storage directory.
334
335       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
341       PASSWORD_STORE_GPG_OPTS
342              Additional options to be passed to all invocations of GPG.
343
344       PASSWORD_STORE_X_SELECTION
345              Overrides the selection passed to xclip, by  default  clipboard.
346              See xclip(1) for more info.
347
348       PASSWORD_STORE_CLIP_TIME
349              Specifies  the  number  of  seconds to wait before restoring the
350              clipboard, by default 45 seconds.
351
352       PASSWORD_STORE_UMASK
353              Sets the umask of all files modified by pass, by default 077.
354
355       PASSWORD_STORE_GENERATED_LENGTH
356              The default password length if the pass-length parameter to gen‐
357              erate is unspecified.
358
359       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
364       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
369       PASSWORD_STORE_ENABLE_EXTENSIONS
370              This  environment  variable must be set to "true" for extensions
371              to be enabled.
372
373       PASSWORD_STORE_EXTENSIONS_DIR
374              The location to look for executable extension files, by  default
375              PASSWORD_STORE_DIR/.extensions.
376
377       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
386       EDITOR The location of the text editor used by edit.
387

SEE ALSO

389       gpg2(1), tr(1), git(1), xclip(1), wl-clipboard(1), qrencode(1).
390
391

AUTHOR

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
395http://www.passwordstore.org/⟩.
396
397

COPYING

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
404       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
409       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.
412
413
414
415ZX2C4                            2014 March 18                         PASS(1)
Impressum