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. Otherwise COMMAND must be one of
  34 the valid commands listed below.
  35
  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
  41 .BR git (1).
  42
  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.
  46
  47 There is a corresponding bash completion script for use with tab completing
  48 password names in
  49 .BR bash (1).
  50
  51 .SH COMMANDS
  52
  53 .TP
  54 \fBinit\fP [ \fI--path=sub-folder\fP, \fI-p sub-folder\fP ] \fIgpg-id...\fP
  55 Initialize new password storage and use
  56 .I gpg-id
  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.
  61 Note that use of
  62 .BR gpg-agent (1)
  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.
  69 .TP
  70 \fBls\fP \fIsubfolder\fP
  71 List names of passwords inside the tree at
  72 .I subfolder
  73 by using the
  74 .BR tree (1)
  75 program. This command is alternatively named \fBlist\fP.
  76 .TP
  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
  80 .BR grep (1)
  81 for matching. Make use of the \fIGREP_OPTIONS\fP environment variable to set particular
  82 options.
  83 .TP
  84 \fBfind\fP \fIpass-names\fP...
  85 List names of passwords inside the tree that match \fIpass-names\fP by using the
  86 .BR tree (1)
  87 program. This command is alternatively named \fBsearch\fP.
  88 .TP
  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
  92 clipboard using
  93 .BR xclip (1)
  94 and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds.
  95 .TP
  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.
 104 .TP
 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
 108 .BR vi (1)
 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.
 113 .TP
 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
 116 .BR pwgen (1)
 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
 121 .BR xclip (1)
 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.
 127 .TP
 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.
 133 .TP
 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.
 140 .TP
 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.
 147 .TP
 148 \fBgit\fP \fIgit-command-args\fP...
 149 If the password store is a git repository, pass \fIgit-command-args\fP as arguments to
 150 .BR git (1)
 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`
 157 .TP
 158 \fBhelp\fP
 159 Show usage message.
 160 .TP
 161 \fBversion\fP
 162 Show version information.
 163
 164 .SH SIMPLE EXAMPLES
 165
 166 .TP
 167 Initialize password store
 168 .B zx2c4@laptop ~ $ pass init [email protected]
 169 .br
 170 mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019]
 171 .br
 172 Password store initialized for [email protected].
 173 .TP
 174 List existing passwords in store
 175 .B zx2c4@laptop ~ $ pass
 176 .br
 177 Password Store
 178 .br
 179 \[u251C]\[u2500]\[u2500] Business
 180 .br
 181 \[u2502]   \[u251C]\[u2500]\[u2500] some-silly-business-site.com
 182 .br
 183 \[u2502]   \[u2514]\[u2500]\[u2500] another-business-site.net
 184 .br
 185 \[u251C]\[u2500]\[u2500] Email
 186 .br
 187 \[u2502]   \[u251C]\[u2500]\[u2500] donenfeld.com
 188 .br
 189 \[u2502]   \[u2514]\[u2500]\[u2500] zx2c4.com
 190 .br
 191 \[u2514]\[u2500]\[u2500] France
 192 .br
 193     \[u251C]\[u2500]\[u2500] bank
 194 .br
 195     \[u251C]\[u2500]\[u2500] freebox
 196 .br
 197     \[u2514]\[u2500]\[u2500] mobilephone
 198 .br
 199
 200 .br
 201 Alternatively, "\fBpass ls\fP".
 202 .TP
 203 Find existing passwords in store that match .com
 204 .B zx2c4@laptop ~ $ pass find .com
 205 .br
 206 Search Terms: .com
 207 .br
 208 \[u251C]\[u2500]\[u2500] Business
 209 .br
 210 \[u2502]   \[u251C]\[u2500]\[u2500] some-silly-business-site.com
 211 .br
 212 \[u2514]\[u2500]\[u2500] Email
 213 .br
 214     \[u251C]\[u2500]\[u2500] donenfeld.com
 215 .br
 216     \[u2514]\[u2500]\[u2500] zx2c4.com
 217 .br
 218
 219 .br
 220 Alternatively, "\fBpass search .com\fP".
 221 .TP
 222 Show existing password
 223 .B zx2c4@laptop ~ $ pass Email/zx2c4.com
 224 .br
 225 sup3rh4x3rizmynam3
 226 .TP
 227 Copy existing password to clipboard
 228 .B zx2c4@laptop ~ $ pass -c Email/zx2c4.com
 229 .br
 230 Copied Email/[email protected] to clipboard. Will clear in 45 seconds.
 231 .TP
 232 Add password to store
 233 .B zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory
 234 .br
 235 Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do
 236 .TP
 237 Add multiline password to store
 238 .B zx2c4@laptop ~ $ pass insert -m Business/cheese-whiz-factory
 239 .br
 240 Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished:
 241 .br
 242
 243 .br
 244 Hey this is my
 245 .br
 246 awesome
 247 .br
 248 multi
 249 .br
 250 line
 251 .br
 252 passworrrrrrrrd.
 253 .br
 254 ^D
 255 .TP
 256 Generate new password
 257 .B zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15
 258 .br
 259 The generated password to Email/jasondonenfeld.com is:
 260 .br
 261 $(-QF&Q=IN2nFBx
 262 .TP
 263 Generate new alphanumeric password
 264 .B zx2c4@laptop ~ $ pass generate -n Email/jasondonenfeld.com 12
 265 .br
 266 The generated password to Email/jasondonenfeld.com is:
 267 .br
 268 YqFsMkBeO6di
 269 .TP
 270 Generate new password and copy it to the clipboard
 271 .B zx2c4@laptop ~ $ pass generate -c Email/jasondonenfeld.com 19
 272 .br
 273 Copied Email/jasondonenfeld.com to clipboard. Will clear in 45 seconds.
 274 .TP
 275 Remove password from store
 276 .B zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory
 277 .br
 278 rm: remove regular file \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]? y
 279 .br
 280 removed \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]
 281
 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
 284 .BR git-push (1)
 285 for more information.
 286
 287 .B zx2c4@laptop ~ $ pass init [email protected]
 288 .br
 289 mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019]
 290 .br
 291 Password store initialized for [email protected].
 292
 293 .B zx2c4@laptop ~ $ pass git init
 294 .br
 295 Initialized empty Git repository in /home/zx2c4/.password-store/.git/
 296 .br
 297 [master (root-commit) 998c8fd] Added current contents of password store.
 298 .br
 299  1 file changed, 1 insertion(+)
 300 .br
 301  create mode 100644 .gpg-id
 302
 303 .B zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store
 304
 305 .B zx2c4@laptop ~ $ pass generate Amazon/[email protected] 21
 306 .br
 307 mkdir: created directory \[u2018]/home/zx2c4/.password-store/Amazon\[u2019]
 308 .br
 309 [master 30fdc1e] Added generated password for Amazon/[email protected] to store.
 310 .br
 311 1 file changed, 0 insertions(+), 0 deletions(-)
 312 .br
 313 create mode 100644 Amazon/[email protected]
 314 .br
 315 The generated password to Amazon/[email protected] is:
 316 .br
 317 <5m,_BrZY`antNDxKN<0A
 318
 319 .B zx2c4@laptop ~ $ pass git push -u --all
 320 .br
 321 Counting objects: 4, done.
 322 .br
 323 Delta compression using up to 2 threads.
 324 .br
 325 Compressing objects: 100% (3/3), done.
 326 .br
 327 Writing objects: 100% (4/4), 921 bytes, done.
 328 .br
 329 Total 4 (delta 0), reused 0 (delta 0)
 330 .br
 331 To kexec.com:pass-store
 332 .br
 333 * [new branch]      master -> master
 334 .br
 335 Branch master set up to track remote branch master from origin.
 336
 337 .B zx2c4@laptop ~ $ pass insert Amazon/[email protected]
 338 .br
 339 Enter password for Amazon/[email protected]: som3r3a11yb1gp4ssw0rd!!88**
 340 .br
 341 [master b9b6746] Added given password for Amazon/[email protected] to store.
 342 .br
 343 1 file changed, 0 insertions(+), 0 deletions(-)
 344 .br
 345 create mode 100644 Amazon/[email protected]
 346
 347 .B zx2c4@laptop ~ $ pass rm Amazon/[email protected]
 348 .br
 349 rm: remove regular file \[u2018]/home/zx2c4/.password-store/Amazon/[email protected]\[u2019]? y
 350 .br
 351 removed \[u2018]/home/zx2c4/.password-store/Amazon/[email protected]\[u2019]
 352 .br
 353 rm 'Amazon/[email protected]'
 354 .br
 355 [master 288b379] Removed Amazon/[email protected] from store.
 356 .br
 357 1 file changed, 0 insertions(+), 0 deletions(-)
 358 .br
 359 delete mode 100644 Amazon/[email protected]
 360
 361 .B zx2c4@laptop ~ $ pass git push
 362 .br
 363 Counting objects: 9, done.
 364 .br
 365 Delta compression using up to 2 threads.
 366 .br
 367 Compressing objects: 100% (5/5), done.
 368 .br
 369 Writing objects: 100% (7/7), 1.25 KiB, done.
 370 .br
 371 Total 7 (delta 0), reused 0 (delta 0)
 372 .br
 373 To kexec.com:pass-store
 374
 375 .SH FILES
 376
 377 .TP
 378 .B ~/.password-store
 379 The default password storage directory.
 380 .TP
 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.
 386
 387 .SH ENVIRONMENT VARIABLES
 388
 389 .TP
 390 .I PASSWORD_STORE_DIR
 391 Overrides the default password storage directory.
 392 .TP
 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.
 397 .TP
 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
 401 password store.
 402 .TP
 403 .I PASSWORD_STORE_GPG_OPTS
 404 Additional options to be passed to all invocations of GPG.
 405 .TP
 406 .I PASSWORD_STORE_X_SELECTION
 407 Overrides the selection passed to \fBxclip\fP, by default \fIclipboard\fP. See
 408 .BR xclip (1)
 409 for more info.
 410 .TP
 411 .I PASSWORD_STORE_CLIP_TIME
 412 Specifies the number of seconds to wait before restoring the clipboard, by default
 413 \fI45\fP seconds.
 414 .TP
 415 .I PASSWORD_STORE_UMASK
 416 Sets the umask of all files modified by pass, by default \fI077\fP.
 417 .TP
 418 .I EDITOR
 419 The location of the text editor used by \fBedit\fP.
 420 .SH SEE ALSO
 421 .BR gpg2 (1),
 422 .BR pwgen (1),
 423 .BR git (1),
 424 .BR xclip (1).
 425
 426 .SH AUTHOR
 427 .B pass
 428 was written by
 429 .MT [email protected]
 430 Jason A. Donenfeld
 431 .ME .
 432 For updates and more information, a project page is available on the
 433 .UR http://\:www.passwordstore.org/
 434 World Wide Web
 435 .UE .
 436
 437 .SH COPYING
 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.
 442
 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.
 447
 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.