pass/share/man/man1/pass.1

   1 .TH PASS 1 "2014 March 18" ZX2C4 "Password Store"
   2
   3 .SH NAME
   4 pass - stores, retrieves, generates, and synchronizes passwords securely
   5
   6 .SH SYNOPSIS
   7 .B pass
   8 [
   9 .I COMMAND
  10 ] [
  11 .I OPTIONS
  12 ]... [
  13 .I ARGS
  14 ]...
  15
  16 .SH DESCRIPTION
  17
  18 .B pass
  19 is a very simple password store that keeps passwords inside
  20 .BR gpg2 (1)
  21 encrypted files inside a simple directory tree residing at
  22 .IR ~/.password-store .
  23 The
  24 .B pass
  25 utility provides a series of commands for manipulating the password store,
  26 allowing the user to add, remove, edit, synchronize, generate, and manipulate
  27 passwords.
  28
  29 If no COMMAND is specified, COMMAND defaults to either
  30 .B show
  31 or
  32 .BR ls ,
  33 depending on the type of specifier in ARGS. Alternatively, if \fIPASSWORD_STORE_ENABLE_EXTENSIONS\fP
  34 is set to "true", and the file \fI.extensions/COMMAND.bash\fP exists inside the
  35 password store and is executable, then it is sourced into the environment,
  36 passing any arguments and environment variables. Extensions existing in a
  37 system-wide directory, only installable by the administrator, are always enabled.
  38
  39 Otherwise COMMAND must be one of the valid commands listed below.
  40
  41 Several of the commands below rely on or provide additional functionality if
  42 the password store directory is also a git repository. If the password store
  43 directory is a git repository, all password store modification commands will
  44 cause a corresponding git commit. Sub-directories may be separate nested git
  45 repositories, and pass will use the inner-most directory relative to the
  46 current password. See the \fIEXTENDED GIT EXAMPLE\fP section for a detailed
  47 description using \fBinit\fP and
  48 .BR git (1).
  49
  50 The \fBinit\fP command must be run before other commands in order to initialize
  51 the password store with the correct gpg key id. Passwords are encrypted using
  52 the gpg key set with \fBinit\fP.
  53
  54 There is a corresponding bash completion script for use with tab completing
  55 password names in
  56 .BR bash (1).
  57
  58 .SH COMMANDS
  59
  60 .TP
  61 \fBinit\fP [ \fI--path=sub-folder\fP, \fI-p sub-folder\fP ] \fIgpg-id...\fP
  62 Initialize new password storage and use
  63 .I gpg-id
  64 for encryption. Multiple gpg-ids may be specified, in order to encrypt each
  65 password with multiple ids. This command must be run first before a password
  66 store can be used. If the specified \fIgpg-id\fP is different from the key
  67 used in any existing files, these files will be reencrypted to use the new id.
  68 Note that use of
  69 .BR gpg-agent (1)
  70 is recommended so that the batch decryption does not require as much user
  71 intervention. If \fI--path\fP or \fI-p\fP is specified, along with an argument,
  72 a specific gpg-id or set of gpg-ids is assigned for that specific sub folder of
  73 the password store. If only one \fIgpg-id\fP is given, and it is an empty string,
  74 then the current \fI.gpg-id\fP file for the specified \fIsub-folder\fP (or root if
  75 unspecified) is removed.
  76 .TP
  77 \fBls\fP \fIsubfolder\fP
  78 List names of passwords inside the tree at
  79 .I subfolder
  80 by using the
  81 .BR tree (1)
  82 program. This command is alternatively named \fBlist\fP.
  83 .TP
  84 \fBgrep\fP \fIsearch-string\fP
  85 Searches inside each decrypted password file for \fIsearch-string\fP, and displays line
  86 containing matched string along with filename. Uses
  87 .BR grep (1)
  88 for matching. Make use of the \fIGREP_OPTIONS\fP environment variable to set particular
  89 options.
  90 .TP
  91 \fBfind\fP \fIpass-names\fP...
  92 List names of passwords inside the tree that match \fIpass-names\fP by using the
  93 .BR tree (1)
  94 program. This command is alternatively named \fBsearch\fP.
  95 .TP
  96 \fBshow\fP [ \fI--clip\fP[=\fIline-number\fP], \fI-c\fP[\fIline-number\fP] ] [ \fI--qrcode\fP[=\fIline-number\fP], \fI-q\fP[\fIline-number\fP] ] \fIpass-name\fP
  97 Decrypt and print a password named \fIpass-name\fP. If \fI--clip\fP or \fI-c\fP
  98 is specified, do not print the password but instead copy the first (or otherwise specified)
  99 line to the clipboard using
 100 .BR xclip (1)
 101 and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds. If \fI--qrcode\fP
 102 or \fI-q\fP is specified, do not print the password but instead display a QR code using
 103 .BR qrencode (1)
 104 either to the terminal or graphically if supported.
 105 .TP
 106 \fBinsert\fP [ \fI--echo\fP, \fI-e\fP | \fI--multiline\fP, \fI-m\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP
 107 Insert a new password into the password store called \fIpass-name\fP. This will
 108 read the new password from standard in. If \fI--echo\fP or \fI-e\fP is \fInot\fP specified,
 109 disable keyboard echo when the password is entered and confirm the password by asking
 110 for it twice. If \fI--multiline\fP or \fI-m\fP is specified, lines will be read until
 111 EOF or Ctrl+D is reached. Otherwise, only a single line from standard in is read. Prompt
 112 before overwriting an existing password, unless \fI--force\fP or \fI-f\fP is specified. This
 113 command is alternatively named \fBadd\fP.
 114 .TP
 115 \fBedit\fP \fIpass-name\fP
 116 Insert a new password or edit an existing password using the default text editor specified
 117 by the environment variable \fIEDITOR\fP or using
 118 .BR vi (1)
 119 as a fallback. This mode makes use of temporary files for editing, but care is taken to
 120 ensure that temporary files are created in \fI/dev/shm\fP in order to avoid writing to
 121 difficult-to-erase disk sectors. If \fI/dev/shm\fP is not accessible, fallback to
 122 the ordinary \fITMPDIR\fP location, and print a warning.
 123 .TP
 124 \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
 125 Generate a new password using \fB/dev/urandom\fP of length \fIpass-length\fP
 126 (or \fIPASSWORD_STORE_GENERATED_LENGTH\fP if unspecified) and insert into
 127 \fIpass-name\fP. If \fI--no-symbols\fP or \fI-n\fP is specified, do not use
 128 any non-alphanumeric characters in the generated password. The character sets used
 129 in generating passwords can be changed with the \fIPASSWORD_STORE_CHARACTER_SET\fP and
 130 \fIPASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS\fP environment variables, described below.
 131 If \fI--clip\fP or \fI-c\fP is specified, do not print the password but instead copy
 132 it to the clipboard using
 133 .BR xclip (1)
 134 and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds. If \fI--qrcode\fP
 135 or \fI-q\fP is specified, do not print the password but instead display a QR code using
 136 .BR qrencode (1)
 137 either to the terminal or graphically if supported. Prompt before overwriting an existing password,
 138 unless \fI--force\fP or \fI-f\fP is specified. If \fI--in-place\fP or \fI-i\fP is
 139 specified, do not interactively prompt, and only replace the first line of the password
 140 file with the new generated password, keeping the remainder of the file intact.
 141 .TP
 142 \fBrm\fP [ \fI--recursive\fP, \fI-r\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP
 143 Remove the password named \fIpass-name\fP from the password store. This command is
 144 alternatively named \fBremove\fP or \fBdelete\fP. If \fI--recursive\fP or \fI-r\fP
 145 is specified, delete pass-name recursively if it is a directory. If \fI--force\fP
 146 or \fI-f\fP is specified, do not interactively prompt before removal.
 147 .TP
 148 \fBmv\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP
 149 Renames the password or directory named \fIold-path\fP to \fInew-path\fP. This
 150 command is alternatively named \fBrename\fP. If \fI--force\fP is specified,
 151 silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a
 152 trailing \fI/\fP, it is always treated as a directory. Passwords are selectively
 153 reencrypted to the corresponding keys of their new destination.
 154 .TP
 155 \fBcp\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP
 156 Copies the password or directory named \fIold-path\fP to \fInew-path\fP. This
 157 command is alternatively named \fBcopy\fP. If \fI--force\fP is specified,
 158 silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a
 159 trailing \fI/\fP, it is always treated as a directory. Passwords are selectively
 160 reencrypted to the corresponding keys of their new destination.
 161 .TP
 162 \fBgit\fP \fIgit-command-args\fP...
 163 If the password store is a git repository, pass \fIgit-command-args\fP as arguments to
 164 .BR git (1)
 165 using the password store as the git repository. If \fIgit-command-args\fP is \fBinit\fP,
 166 in addition to initializing the git repository, add the current contents of the password
 167 store to the repository in an initial commit. If the git config key \fIpass.signcommits\fP
 168 is set to \fItrue\fP, then all commits will be signed using \fIuser.signingkey\fP or the
 169 default git signing key. This config key may be turned on using:
 170 .B `pass git config --bool --add pass.signcommits true`
 171 .TP
 172 \fBhelp\fP
 173 Show usage message.
 174 .TP
 175 \fBversion\fP
 176 Show version information.
 177
 178 .SH SIMPLE EXAMPLES
 179
 180 .TP
 181 Initialize password store
 182 .B zx2c4@laptop ~ $ pass init [email protected]
 183 .br
 184 mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019]
 185 .br
 186 Password store initialized for [email protected].
 187 .TP
 188 List existing passwords in store
 189 .B zx2c4@laptop ~ $ pass
 190 .br
 191 Password Store
 192 .br
 193 \[u251C]\[u2500]\[u2500] Business
 194 .br
 195 \[u2502]   \[u251C]\[u2500]\[u2500] some-silly-business-site.com
 196 .br
 197 \[u2502]   \[u2514]\[u2500]\[u2500] another-business-site.net
 198 .br
 199 \[u251C]\[u2500]\[u2500] Email
 200 .br
 201 \[u2502]   \[u251C]\[u2500]\[u2500] donenfeld.com
 202 .br
 203 \[u2502]   \[u2514]\[u2500]\[u2500] zx2c4.com
 204 .br
 205 \[u2514]\[u2500]\[u2500] France
 206 .br
 207     \[u251C]\[u2500]\[u2500] bank
 208 .br
 209     \[u251C]\[u2500]\[u2500] freebox
 210 .br
 211     \[u2514]\[u2500]\[u2500] mobilephone
 212 .br
 213
 214 .br
 215 Alternatively, "\fBpass ls\fP".
 216 .TP
 217 Find existing passwords in store that match .com
 218 .B zx2c4@laptop ~ $ pass find .com
 219 .br
 220 Search Terms: .com
 221 .br
 222 \[u251C]\[u2500]\[u2500] Business
 223 .br
 224 \[u2502]   \[u251C]\[u2500]\[u2500] some-silly-business-site.com
 225 .br
 226 \[u2514]\[u2500]\[u2500] Email
 227 .br
 228     \[u251C]\[u2500]\[u2500] donenfeld.com
 229 .br
 230     \[u2514]\[u2500]\[u2500] zx2c4.com
 231 .br
 232
 233 .br
 234 Alternatively, "\fBpass search .com\fP".
 235 .TP
 236 Show existing password
 237 .B zx2c4@laptop ~ $ pass Email/zx2c4.com
 238 .br
 239 sup3rh4x3rizmynam3
 240 .TP
 241 Copy existing password to clipboard
 242 .B zx2c4@laptop ~ $ pass -c Email/zx2c4.com
 243 .br
 244 Copied Email/[email protected] to clipboard. Will clear in 45 seconds.
 245 .TP
 246 Add password to store
 247 .B zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory
 248 .br
 249 Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do
 250 .TP
 251 Add multiline password to store
 252 .B zx2c4@laptop ~ $ pass insert -m Business/cheese-whiz-factory
 253 .br
 254 Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished:
 255 .br
 256
 257 .br
 258 Hey this is my
 259 .br
 260 awesome
 261 .br
 262 multi
 263 .br
 264 line
 265 .br
 266 passworrrrrrrrd.
 267 .br
 268 ^D
 269 .TP
 270 Generate new password
 271 .B zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15
 272 .br
 273 The generated password to Email/jasondonenfeld.com is:
 274 .br
 275 $(-QF&Q=IN2nFBx
 276 .TP
 277 Generate new alphanumeric password
 278 .B zx2c4@laptop ~ $ pass generate -n Email/jasondonenfeld.com 12
 279 .br
 280 The generated password to Email/jasondonenfeld.com is:
 281 .br
 282 YqFsMkBeO6di
 283 .TP
 284 Generate new password and copy it to the clipboard
 285 .B zx2c4@laptop ~ $ pass generate -c Email/jasondonenfeld.com 19
 286 .br
 287 Copied Email/jasondonenfeld.com to clipboard. Will clear in 45 seconds.
 288 .TP
 289 Remove password from store
 290 .B zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory
 291 .br
 292 rm: remove regular file \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]? y
 293 .br
 294 removed \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]
 295
 296 .SH EXTENDED GIT EXAMPLE
 297 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
 298 .BR git-push (1)
 299 for more information.
 300
 301 .B zx2c4@laptop ~ $ pass init [email protected]
 302 .br
 303 mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019]
 304 .br
 305 Password store initialized for [email protected].
 306
 307 .B zx2c4@laptop ~ $ pass git init
 308 .br
 309 Initialized empty Git repository in /home/zx2c4/.password-store/.git/
 310 .br
 311 [master (root-commit) 998c8fd] Added current contents of password store.
 312 .br
 313  1 file changed, 1 insertion(+)
 314 .br
 315  create mode 100644 .gpg-id
 316
 317 .B zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store
 318
 319 .B zx2c4@laptop ~ $ pass generate Amazon/[email protected] 21
 320 .br
 321 mkdir: created directory \[u2018]/home/zx2c4/.password-store/Amazon\[u2019]
 322 .br
 323 [master 30fdc1e] Added generated password for Amazon/[email protected] to store.
 324 .br
 325 1 file changed, 0 insertions(+), 0 deletions(-)
 326 .br
 327 create mode 100644 Amazon/[email protected]
 328 .br
 329 The generated password to Amazon/[email protected] is:
 330 .br
 331 <5m,_BrZY`antNDxKN<0A
 332
 333 .B zx2c4@laptop ~ $ pass git push -u --all
 334 .br
 335 Counting objects: 4, done.
 336 .br
 337 Delta compression using up to 2 threads.
 338 .br
 339 Compressing objects: 100% (3/3), done.
 340 .br
 341 Writing objects: 100% (4/4), 921 bytes, done.
 342 .br
 343 Total 4 (delta 0), reused 0 (delta 0)
 344 .br
 345 To kexec.com:pass-store
 346 .br
 347 * [new branch]      master -> master
 348 .br
 349 Branch master set up to track remote branch master from origin.
 350
 351 .B zx2c4@laptop ~ $ pass insert Amazon/[email protected]
 352 .br
 353 Enter password for Amazon/[email protected]: som3r3a11yb1gp4ssw0rd!!88**
 354 .br
 355 [master b9b6746] Added given password for Amazon/[email protected] to store.
 356 .br
 357 1 file changed, 0 insertions(+), 0 deletions(-)
 358 .br
 359 create mode 100644 Amazon/[email protected]
 360
 361 .B zx2c4@laptop ~ $ pass rm Amazon/[email protected]
 362 .br
 363 rm: remove regular file \[u2018]/home/zx2c4/.password-store/Amazon/[email protected]\[u2019]? y
 364 .br
 365 removed \[u2018]/home/zx2c4/.password-store/Amazon/[email protected]\[u2019]
 366 .br
 367 rm 'Amazon/[email protected]'
 368 .br
 369 [master 288b379] Removed Amazon/[email protected] from store.
 370 .br
 371 1 file changed, 0 insertions(+), 0 deletions(-)
 372 .br
 373 delete mode 100644 Amazon/[email protected]
 374
 375 .B zx2c4@laptop ~ $ pass git push
 376 .br
 377 Counting objects: 9, done.
 378 .br
 379 Delta compression using up to 2 threads.
 380 .br
 381 Compressing objects: 100% (5/5), done.
 382 .br
 383 Writing objects: 100% (7/7), 1.25 KiB, done.
 384 .br
 385 Total 7 (delta 0), reused 0 (delta 0)
 386 .br
 387 To kexec.com:pass-store
 388
 389 .SH FILES
 390
 391 .TP
 392 .B ~/.password-store
 393 The default password storage directory.
 394 .TP
 395 .B ~/.password-store/.gpg-id
 396 Contains the default gpg key identification used for encryption and decryption.
 397 Multiple gpg keys may be specified in this file, one per line. If this file
 398 exists in any sub directories, passwords inside those sub directories are
 399 encrypted using those keys. This should be set using the \fBinit\fP command.
 400 .TP
 401 .B ~/.password-store/.extensions
 402 The directory containing extension files.
 403
 404 .SH ENVIRONMENT VARIABLES
 405
 406 .TP
 407 .I PASSWORD_STORE_DIR
 408 Overrides the default password storage directory.
 409 .TP
 410 .I PASSWORD_STORE_KEY
 411 Overrides the default gpg key identification set by \fBinit\fP. Keys must not
 412 contain spaces and thus use of the hexadecimal key signature is recommended.
 413 Multiple keys may be specified separated by spaces.
 414 .TP
 415 .I PASSWORD_STORE_GPG_OPTS
 416 Additional options to be passed to all invocations of GPG.
 417 .TP
 418 .I PASSWORD_STORE_X_SELECTION
 419 Overrides the selection passed to \fBxclip\fP, by default \fIclipboard\fP. See
 420 .BR xclip (1)
 421 for more info.
 422 .TP
 423 .I PASSWORD_STORE_CLIP_TIME
 424 Specifies the number of seconds to wait before restoring the clipboard, by default
 425 \fI45\fP seconds.
 426 .TP
 427 .I PASSWORD_STORE_UMASK
 428 Sets the umask of all files modified by pass, by default \fI077\fP.
 429 .TP
 430 .I PASSWORD_STORE_GENERATED_LENGTH
 431 The default password length if the \fIpass-length\fP parameter to \fBgenerate\fP
 432 is unspecified.
 433 .TP
 434 .I PASSWORD_STORE_CHARACTER_SET
 435 The character set to be used in password generation for \fBgenerate\fP. This value
 436 is to be interpreted by \fBtr\fP. See
 437 .BR tr (1)
 438 for more info.
 439 .TP
 440 .I PASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS
 441 The character set to be used in no-symbol password generation for \fBgenerate\fP,
 442 when \fI--no-symbols\fP, \fI-n\fP is specified. This value is to be interpreted
 443 by \fBtr\fP. See
 444 .BR tr (1)
 445 for more info.
 446 .TP
 447 .I PASSWORD_STORE_ENABLE_EXTENSIONS
 448 This environment variable must be set to "true" for extensions to be enabled.
 449 .TP
 450 .I PASSWORD_STORE_EXTENSIONS_DIR
 451 The location to look for executable extension files, by default
 452 \fIPASSWORD_STORE_DIR/.extensions\fP.
 453 .TP
 454 .I PASSWORD_STORE_SIGNING_KEY
 455 If this environment variable is set, then all \fB.gpg-id\fP files and non-system extension files
 456 must be signed using a detached signature using the GPG key specified by the full 40 character
 457 upper-case fingerprint in this variable. If multiple fingerprints are specified, each
 458 separated by a whitespace character, then signatures must match at least one.
 459 The \fBinit\fP command will keep signatures of \fB.gpg-id\fP files up to date.
 460 .TP
 461 .I EDITOR
 462 The location of the text editor used by \fBedit\fP.
 463 .SH SEE ALSO
 464 .BR gpg2 (1),
 465 .BR tr (1),
 466 .BR git (1),
 467 .BR xclip (1),
 468 .BR qrencode (1).
 469
 470 .SH AUTHOR
 471 .B pass
 472 was written by
 473 .MT [email protected]
 474 Jason A. Donenfeld
 475 .ME .
 476 For updates and more information, a project page is available on the
 477 .UR http://\:www.passwordstore.org/
 478 World Wide Web
 479 .UE .
 480
 481 .SH COPYING
 482 This program is free software; you can redistribute it and/or
 483 modify it under the terms of the GNU General Public License
 484 as published by the Free Software Foundation; either version 2
 485 of the License, or (at your option) any later version.
 486
 487 This program is distributed in the hope that it will be useful,
 488 but WITHOUT ANY WARRANTY; without even the implied warranty of
 489 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 490 GNU General Public License for more details.
 491
 492 You should have received a copy of the GNU General Public License
 493 along with this program; if not, write to the Free Software
 494 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.