--- /dev/null
+.TH PASS 1 "2014 March 18" ZX2C4 "Password Store"
+
+.SH NAME
+pass - stores, retrieves, generates, and synchronizes passwords securely
+
+.SH SYNOPSIS
+.B pass
+[
+.I COMMAND
+] [
+.I OPTIONS
+]... [
+.I ARGS
+]...
+
+.SH DESCRIPTION
+
+.B pass
+is a very simple password store that keeps passwords inside
+.BR gpg2 (1)
+encrypted files inside a simple directory tree residing at
+.IR ~/.password-store .
+The
+.B pass
+utility provides a series of commands for manipulating the password store,
+allowing the user to add, remove, edit, synchronize, generate, and manipulate
+passwords.
+
+If no COMMAND is specified, COMMAND defaults to either
+.B show
+or
+.BR ls ,
+depending on the type of specifier in ARGS. Otherwise COMMAND must be one of
+the valid commands listed below.
+
+Several of the commands below rely on or provide additional functionality if
+the password store directory is also a git repository. If the password store
+directory is a git repository, all password store modification commands will
+cause a corresponding git commit. See the \fIEXTENDED GIT EXAMPLE\fP section
+for a detailed description using \fBinit\fP and
+.BR git (1).
+
+The \fBinit\fP command must be run before other commands in order to initialize
+the password store with the correct gpg key id. Passwords are encrypting using
+the gpg key set with \fBinit\fP.
+
+There is a corresponding bash completion script for use with tab completing
+password names in
+.BR bash (1).
+
+.SH COMMANDS
+
+.TP
+\fBinit\fP [ \fI--path=sub-folder\fP, \fI-p sub-folder\fP ] \fIgpg-id...\fP
+Initialize new password storage and use
+.I gpg-id
+for encryption. Multiple gpg-ids may be specified, in order to encrypt each
+password with multiple ids. This command must be run first before a password
+store can be used. If the specified \fIgpg-id\fP is different from the key
+used in any existing files, these files will be reencrypted to use the new id.
+Note that use of
+.BR gpg-agent (1)
+is recommended so that the batch decryption does not require as much user
+intervention. If \fI--path\fP or \fI-p\fP is specified, along with an argument,
+a specific gpg-id or set of gpg-ids is assigned for that specific sub folder of
+the password store. If only one \fIgpg-id\fP is given, and it is an empty string,
+then the current \fI.gpg-id\fP file for the specified \fIsub-folder\fP (or root if
+unspecified) is removed.
+.TP
+\fBls\fP \fIsubfolder\fP
+List names of passwords inside the tree at
+.I subfolder
+by using the
+.BR tree (1)
+program. This command is alternatively named \fBlist\fP.
+.TP
+\fBgrep\fP \fIsearch-string\fP
+Searches inside each decrypted password file for \fIsearch-string\fP, and displays line
+containing matched string along with filename. Uses
+.BR grep (1)
+for matching. Make use of the \fIGREP_OPTIONS\fP environment variable to set particular
+options.
+.TP
+\fBfind\fP \fIpass-names\fP...
+List names of passwords inside the tree that match \fIpass-names\fP by using the
+.BR tree (1)
+program. This command is alternatively named \fBsearch\fP.
+.TP
+\fBshow\fP [ \fI--clip\fP, \fI-c\fP ] \fIpass-name\fP
+Decrypt and print a password named \fIpass-name\fP. If \fI--clip\fP or \fI-c\fP
+is specified, do not print the password but instead copy the first line to the
+clipboard using
+.BR xclip (1)
+and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds.
+.TP
+\fBinsert\fP [ \fI--echo\fP, \fI-e\fP | \fI--multiline\fP, \fI-m\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP
+Insert a new password into the password store called \fIpass-name\fP. This will
+read the new password from standard in. If \fI--echo\fP or \fI-e\fP is \fInot\fP specified,
+disable keyboard echo when the password is entered and confirm the password by asking
+for it twice. If \fI--multiline\fP or \fI-m\fP is specified, lines will be read until
+EOF or Ctrl+D is reached. Otherwise, only a single line from standard in is read. Prompt
+before overwriting an existing password, unless \fI--force\fP or \fI-f\fP is specified. This
+command is alternatively named \fBadd\fP.
+.TP
+\fBedit\fP \fIpass-name\fP
+Insert a new password or edit an existing password using the default text editor specified
+by the environment variable \fIEDITOR\fP or using
+.BR vi (1)
+as a fallback. This mode makes use of temporary files for editing, but care is taken to
+ensure that temporary files are created in \fI/dev/shm\fP in order to avoid writing to
+difficult-to-erase disk sectors. If \fI/dev/shm\fP is not accessible, fallback to
+the ordinary \fITMPDIR\fP location, and print a warning.
+.TP
+\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
+Generate a new password using
+.BR pwgen (1)
+of length \fIpass-length\fP and insert into \fIpass-name\fP. If \fI--no-symbols\fP or \fI-n\fP
+is specified, do not use any non-alphanumeric characters in the generated password.
+If \fI--clip\fP or \fI-c\fP is specified, do not print the password but instead copy
+it to the clipboard using
+.BR xclip (1)
+and then restore the clipboard after 45 (or \fIPASSWORD_STORE_CLIP_TIME\fP) seconds.
+Prompt before overwriting an existing password,
+unless \fI--force\fP or \fI-f\fP is specified. If \fI--in-place\fP or \fI-i\fP is
+specified, do not interactively prompt, and only replace the first line of the password
+file with the new generated password, keeping the remainder of the file intact.
+.TP
+\fBrm\fP [ \fI--recursive\fP, \fI-r\fP ] [ \fI--force\fP, \fI-f\fP ] \fIpass-name\fP
+Remove the password named \fIpass-name\fP from the password store. This command is
+alternatively named \fBremove\fP or \fBdelete\fP. If \fI--recursive\fP or \fI-r\fP
+is specified, delete pass-name recursively if it is a directory. If \fI--force\fP
+or \fI-f\fP is specified, do not interactively prompt before removal.
+.TP
+\fBmv\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP
+Renames the password or directory named \fIold-path\fP to \fInew-path\fP. This
+command is alternatively named \fBrename\fP. If \fI--force\fP is specified,
+silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a
+trailing \fI/\fP, it is always treated as a directory. Passwords are selectively
+reencrypted to the corresponding keys of their new destination.
+.TP
+\fBcp\fP [ \fI--force\fP, \fI-f\fP ] \fIold-path\fP \fInew-path\fP
+Copies the password or directory named \fIold-path\fP to \fInew-path\fP. This
+command is alternatively named \fBcopy\fP. If \fI--force\fP is specified,
+silently overwrite \fInew-path\fP if it exists. If \fInew-path\fP ends in a
+trailing \fI/\fP, it is always treated as a directory. Passwords are selectively
+reencrypted to the corresponding keys of their new destination.
+.TP
+\fBgit\fP \fIgit-command-args\fP...
+If the password store is a git repository, pass \fIgit-command-args\fP as arguments to
+.BR git (1)
+using the password store as the git repository. If \fIgit-command-args\fP is \fBinit\fP,
+in addition to initializing the git repository, add the current contents of the password
+store to the repository in an initial commit. If the git config key \fIpass.signcommits\fP
+is set to \fItrue\fP, then all commits will be signed using \fIuser.signingkey\fP or the
+default git signing key. This config key may be turned on using:
+.B `pass git config --bool --add pass.signcommits true`
+.TP
+\fBhelp\fP
+Show usage message.
+.TP
+\fBversion\fP
+Show version information.
+
+.SH SIMPLE EXAMPLES
+
+.TP
+Initialize password store
+.br
+mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019]
+.br
+.TP
+List existing passwords in store
+.B zx2c4@laptop ~ $ pass
+.br
+Password Store
+.br
+\[u251C]\[u2500]\[u2500] Business
+.br
+\[u2502] \[u251C]\[u2500]\[u2500] some-silly-business-site.com
+.br
+\[u2502] \[u2514]\[u2500]\[u2500] another-business-site.net
+.br
+\[u251C]\[u2500]\[u2500] Email
+.br
+\[u2502] \[u251C]\[u2500]\[u2500] donenfeld.com
+.br
+\[u2502] \[u2514]\[u2500]\[u2500] zx2c4.com
+.br
+\[u2514]\[u2500]\[u2500] France
+.br
+ \[u251C]\[u2500]\[u2500] bank
+.br
+ \[u251C]\[u2500]\[u2500] freebox
+.br
+ \[u2514]\[u2500]\[u2500] mobilephone
+.br
+
+.br
+Alternatively, "\fBpass ls\fP".
+.TP
+Find existing passwords in store that match .com
+.B zx2c4@laptop ~ $ pass find .com
+.br
+Search Terms: .com
+.br
+\[u251C]\[u2500]\[u2500] Business
+.br
+\[u2502] \[u251C]\[u2500]\[u2500] some-silly-business-site.com
+.br
+\[u2514]\[u2500]\[u2500] Email
+.br
+ \[u251C]\[u2500]\[u2500] donenfeld.com
+.br
+ \[u2514]\[u2500]\[u2500] zx2c4.com
+.br
+
+.br
+Alternatively, "\fBpass search .com\fP".
+.TP
+Show existing password
+.B zx2c4@laptop ~ $ pass Email/zx2c4.com
+.br
+sup3rh4x3rizmynam3
+.TP
+Copy existing password to clipboard
+.B zx2c4@laptop ~ $ pass -c Email/zx2c4.com
+.br
+.TP
+Add password to store
+.B zx2c4@laptop ~ $ pass insert Business/cheese-whiz-factory
+.br
+Enter password for Business/cheese-whiz-factory: omg so much cheese what am i gonna do
+.TP
+Add multiline password to store
+.B zx2c4@laptop ~ $ pass insert -m Business/cheese-whiz-factory
+.br
+Enter contents of Business/cheese-whiz-factory and press Ctrl+D when finished:
+.br
+
+.br
+Hey this is my
+.br
+awesome
+.br
+multi
+.br
+line
+.br
+passworrrrrrrrd.
+.br
+^D
+.TP
+Generate new password
+.B zx2c4@laptop ~ $ pass generate Email/jasondonenfeld.com 15
+.br
+The generated password to Email/jasondonenfeld.com is:
+.br
+$(-QF&Q=IN2nFBx
+.TP
+Generate new alphanumeric password
+.B zx2c4@laptop ~ $ pass generate -n Email/jasondonenfeld.com 12
+.br
+The generated password to Email/jasondonenfeld.com is:
+.br
+YqFsMkBeO6di
+.TP
+Generate new password and copy it to the clipboard
+.B zx2c4@laptop ~ $ pass generate -c Email/jasondonenfeld.com 19
+.br
+Copied Email/jasondonenfeld.com to clipboard. Will clear in 45 seconds.
+.TP
+Remove password from store
+.B zx2c4@laptop ~ $ pass remove Business/cheese-whiz-factory
+.br
+rm: remove regular file \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]? y
+.br
+removed \[u2018]/home/zx2c4/.password-store/Business/cheese-whiz-factory.gpg\[u2019]
+
+.SH EXTENDED GIT EXAMPLE
+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
+.BR git-push (1)
+for more information.
+
+.br
+mkdir: created directory \[u2018]/home/zx2c4/.password-store\[u2019]
+.br
+
+.B zx2c4@laptop ~ $ pass git init
+.br
+Initialized empty Git repository in /home/zx2c4/.password-store/.git/
+.br
+[master (root-commit) 998c8fd] Added current contents of password store.
+.br
+ 1 file changed, 1 insertion(+)
+.br
+ create mode 100644 .gpg-id
+
+.B zx2c4@laptop ~ $ pass git remote add origin kexec.com:pass-store
+
+.br
+mkdir: created directory \[u2018]/home/zx2c4/.password-store/Amazon\[u2019]
+.br
+.br
+1 file changed, 0 insertions(+), 0 deletions(-)
+.br
+.br
+.br
+<5m,_BrZY`antNDxKN<0A
+
+.B zx2c4@laptop ~ $ pass git push -u --all
+.br
+Counting objects: 4, done.
+.br
+Delta compression using up to 2 threads.
+.br
+Compressing objects: 100% (3/3), done.
+.br
+Writing objects: 100% (4/4), 921 bytes, done.
+.br
+Total 4 (delta 0), reused 0 (delta 0)
+.br
+To kexec.com:pass-store
+.br
+* [new branch] master -> master
+.br
+Branch master set up to track remote branch master from origin.
+
+.br
+.br
+.br
+1 file changed, 0 insertions(+), 0 deletions(-)
+.br
+
+.br
+rm: remove regular file \[u2018]/home/zx2c4/.password-store/Amazon/
[email protected]\[u2019]? y
+.br
+.br
+.br
+.br
+1 file changed, 0 insertions(+), 0 deletions(-)
+.br
+
+.B zx2c4@laptop ~ $ pass git push
+.br
+Counting objects: 9, done.
+.br
+Delta compression using up to 2 threads.
+.br
+Compressing objects: 100% (5/5), done.
+.br
+Writing objects: 100% (7/7), 1.25 KiB, done.
+.br
+Total 7 (delta 0), reused 0 (delta 0)
+.br
+To kexec.com:pass-store
+
+.SH FILES
+
+.TP
+.B ~/.password-store
+The default password storage directory.
+.TP
+.B ~/.password-store/.gpg-id
+Contains the default gpg key identification used for encryption and decryption.
+Multiple gpg keys may be specified in this file, one per line. If this file
+exists in any sub directories, passwords inside those sub directories are
+encrypted using those keys. This should be set using the \fBinit\fP command.
+
+.SH ENVIRONMENT VARIABLES
+
+.TP
+.I PASSWORD_STORE_DIR
+Overrides the default password storage directory.
+.TP
+.I PASSWORD_STORE_KEY
+Overrides the default gpg key identification set by \fBinit\fP. Keys must not
+contain spaces and thus use of the hexidecimal key signature is recommended.
+Multiple keys may be specified separated by spaces.
+.TP
+.I PASSWORD_STORE_GIT
+Overrides the default root of the git repository, which is helpful if
+\fIPASSWORD_STORE_DIR\fP is temporarily set to a sub-directory of the default
+password store.
+.TP
+.I PASSWORD_STORE_GPG_OPTS
+Additional options to be passed to all invocations of GPG.
+.TP
+.I PASSWORD_STORE_X_SELECTION
+Overrides the selection passed to \fBxclip\fP, by default \fIclipboard\fP. See
+.BR xclip (1)
+for more info.
+.TP
+.I PASSWORD_STORE_CLIP_TIME
+Specifies the number of seconds to wait before restoring the clipboard, by default
+\fI45\fP seconds.
+.TP
+.I PASSWORD_STORE_UMASK
+Sets the umask of all files modified by pass, by default \fI077\fP.
+.TP
+.I EDITOR
+The location of the text editor used by \fBedit\fP.
+.SH SEE ALSO
+.BR gpg2 (1),
+.BR pwgen (1),
+.BR git (1),
+.BR xclip (1).
+
+.SH AUTHOR
+.B pass
+was written by
+Jason A. Donenfeld
+.ME .
+For updates and more information, a project page is available on the
+.UR http://\:www.passwordstore.org/
+World Wide Web
+.UE .
+
+.SH COPYING
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
git.ucc.asn.au / zanchey / uccpass.git / blobdiff
UCC git Repository :: git.ucc.asn.au