1 e346be82 2022-06-29 op .\" Copyright (c) 2021, 2022 Omar Polo <op@omarpolo.com>
  2 e346be82 2022-06-29 op .\"
  3 e346be82 2022-06-29 op .\" Permission to use, copy, modify, and distribute this software for any
  4 e346be82 2022-06-29 op .\" purpose with or without fee is hereby granted, provided that the above
  5 e346be82 2022-06-29 op .\" copyright notice and this permission notice appear in all copies.
  6 e346be82 2022-06-29 op .\"
  7 e346be82 2022-06-29 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  8 e346be82 2022-06-29 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  9 e346be82 2022-06-29 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 10 e346be82 2022-06-29 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 11 e346be82 2022-06-29 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 12 e346be82 2022-06-29 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 13 e346be82 2022-06-29 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 14 a4ca9752 2022-10-01 op .Dd October 1, 2022
 15 e346be82 2022-06-29 op .Dt PLASS 1
 16 e346be82 2022-06-29 op .Os
 17 e346be82 2022-06-29 op .Sh NAME
 18 e346be82 2022-06-29 op .Nm plass
 19 e346be82 2022-06-29 op .Nd manage passwords
 20 e346be82 2022-06-29 op .Sh SYNOPSIS
 21 e346be82 2022-06-29 op .Nm
 22 e346be82 2022-06-29 op .Op Fl h
 23 5a0f0861 2022-09-09 op .Ar command
 24 5a0f0861 2022-09-09 op .Op Ar argument ...
 25 e346be82 2022-06-29 op .Sh DESCRIPTION
 26 e346be82 2022-06-29 op .Nm
 27 e346be82 2022-06-29 op is a simple password manager.
 28 2a7970ee 2022-10-01 op Passwords are stored as a directory tree where every password is a
 29 2a7970ee 2022-10-01 op file encrypted with
 30 5a0f0861 2022-09-09 op .Xr gpg 1 .
 31 e346be82 2022-06-29 op .Pp
 32 2a7970ee 2022-10-01 op A password store is a
 33 2a7970ee 2022-10-01 op .Xr got 1
 34 2a7970ee 2022-10-01 op repository with a worktree checked out at
 35 2a7970ee 2022-10-01 op .Pa ~/.password-store
 36 2a7970ee 2022-10-01 op .Pq or Ev PLASS_STORE .
 37 2a7970ee 2022-10-01 op The only restriction is that a special file called
 38 2a7970ee 2022-10-01 op .Pa .gpg-id
 39 2a7970ee 2022-10-01 op containing the GPG recipient must exist in the root of the directory tree
 40 2a7970ee 2022-10-01 op for most
 41 2a7970ee 2022-10-01 op .Nm
 42 2a7970ee 2022-10-01 op commands to work.
 43 2a7970ee 2022-10-01 op .Pp
 44 e346be82 2022-06-29 op Password entries can be referenced using the path relative to the
 45 e346be82 2022-06-29 op store directory.
 46 2a7970ee 2022-10-01 op The file extension
 47 e346be82 2022-06-29 op .Dq \&.gpg
 48 e346be82 2022-06-29 op is optional.
 49 e346be82 2022-06-29 op .Pp
 50 e346be82 2022-06-29 op The following commands are available:
 51 e346be82 2022-06-29 op .Bl -tag -width Ds
 52 e346be82 2022-06-29 op .It Cm cat Ar entries ...
 53 2a7970ee 2022-10-01 op Decrypt and print the content of
 54 5a0f0861 2022-09-09 op .Ar entries
 55 5a0f0861 2022-09-09 op in the given order.
 56 e346be82 2022-06-29 op .It Cm find Op Ar pattern
 57 2a7970ee 2022-10-01 op Print the entries of the store one per line, optionally filtered by
 58 e346be82 2022-06-29 op .Ar pattern .
 59 2a7970ee 2022-10-01 op .It Cm gen Oo Fl nq Oc Oo Fl c Ar chars Oc Oo Fl l Ar length Oc Ar entry
 60 e346be82 2022-06-29 op Generate and persist a password for the given
 61 e346be82 2022-06-29 op .Ar entry
 62 e346be82 2022-06-29 op in the store.
 63 e346be82 2022-06-29 op .Fl c
 64 e346be82 2022-06-29 op can be used to control the characters allowed in the password
 65 e346be82 2022-06-29 op (by default
 66 e346be82 2022-06-29 op .Dq !-~
 67 e346be82 2022-06-29 op i.e. all the printable ASCII characters)
 68 e346be82 2022-06-29 op and
 69 e346be82 2022-06-29 op .Fl l
 70 e346be82 2022-06-29 op the length
 71 e346be82 2022-06-29 op .Pq 32 by default .
 72 e346be82 2022-06-29 op Unless the
 73 e346be82 2022-06-29 op .Fl q
 74 2a7970ee 2022-10-01 op flag is provided, print the generated password.
 75 e346be82 2022-06-29 op If the
 76 e346be82 2022-06-29 op .Fl n
 77 8bd06def 2022-10-01 op flag is given the password won't be persisted and the
 78 8bd06def 2022-10-01 op .Ar entry
 79 8bd06def 2022-10-01 op argument is optional.
 80 e346be82 2022-06-29 op .It Cm mv Ar from Ar to
 81 e346be82 2022-06-29 op Rename a password entry, doesn't work with directories.
 82 e346be82 2022-06-29 op .Ar from
 83 2a7970ee 2022-10-01 op must exist and
 84 e346be82 2022-06-29 op .Ar to
 85 e346be82 2022-06-29 op mustn't.
 86 e346be82 2022-06-29 op .It Cm rm Ar entries ...
 87 e346be82 2022-06-29 op Remove the given
 88 e346be82 2022-06-29 op .Ar entries
 89 e346be82 2022-06-29 op from the store.
 90 e346be82 2022-06-29 op .It Cm tee Oo Fl q Oc Ar entry
 91 e346be82 2022-06-29 op Prompt for a password and persist it into the store under the given
 92 e346be82 2022-06-29 op .Ar entry
 93 5a0f0861 2022-09-09 op name and the print it again on the standard output unless the
 94 e346be82 2022-06-29 op .Fl q
 95 5a0f0861 2022-09-09 op option is given.
 96 e346be82 2022-06-29 op .El
 97 e346be82 2022-06-29 op .Sh ENVIRONMENT
 98 e346be82 2022-06-29 op .Bl -tag -width Ds
 99 e346be82 2022-06-29 op .It Ev PLASS_CHARS
100 e346be82 2022-06-29 op default range of characters to use to generate passwords.
101 e346be82 2022-06-29 op .It Ev PLASS_GOT
102 e346be82 2022-06-29 op Path to the
103 e346be82 2022-06-29 op .Xr got 1
104 e346be82 2022-06-29 op executable.
105 e346be82 2022-06-29 op .It Ev PLASS_GPG
106 e346be82 2022-06-29 op Path to the
107 5a0f0861 2022-09-09 op .Xr gpg 1
108 e346be82 2022-06-29 op executable.
109 e346be82 2022-06-29 op .It Ev PLASS_LENGTH
110 e346be82 2022-06-29 op Default length for the generated passwords.
111 e346be82 2022-06-29 op .It Ev PLASS_STORE
112 e346be82 2022-06-29 op Path to the password store directory tree.
113 e346be82 2022-06-29 op .El
114 e346be82 2022-06-29 op .Sh FILES
115 e346be82 2022-06-29 op .Bl -tag -width Ds
116 e346be82 2022-06-29 op .It Pa ~/.password-store
117 e346be82 2022-06-29 op Password store used by default.
118 e346be82 2022-06-29 op .It Pa ~/.password-store/.gpg-id
119 2a7970ee 2022-10-01 op File containing the GPG recipient used to encrypt the passwords.
120 e346be82 2022-06-29 op .El
121 2a7970ee 2022-10-01 op .Sh EXAMPLES
122 2a7970ee 2022-10-01 op A got repository and password store can be initialized as follows:
123 2a7970ee 2022-10-01 op .Bd -literal -offset indent
124 2a7970ee 2022-10-01 op $ mkdir ~/.password-store
125 2a7970ee 2022-10-01 op $ echo foo@example.com > ~/.password-store/.gpg-id
126 2a7970ee 2022-10-01 op $ gotadmin init ~/git/pass.git
127 2a7970ee 2022-10-01 op $ got import -r ~/git/pass.git -m 'initial import' ~/.password-store
128 2a7970ee 2022-10-01 op $ got checkout -E ~/git/pass.git ~/.password-store
129 2a7970ee 2022-10-01 op .Ed
130 2a7970ee 2022-10-01 op .Pp
131 2a7970ee 2022-10-01 op see
132 2a7970ee 2022-10-01 op .Xr got 1
133 2a7970ee 2022-10-01 op for more information.
134 2a7970ee 2022-10-01 op .Pp
135 2a7970ee 2022-10-01 op To migrate from
136 2a7970ee 2022-10-01 op .Xr pass 1 ,
137 2a7970ee 2022-10-01 op delete
138 2a7970ee 2022-10-01 op .Pa ~/.password-store
139 2a7970ee 2022-10-01 op and check out it again using
140 2a7970ee 2022-10-01 op .Xr got 1 .
141 2a7970ee 2022-10-01 op .Pp
142 2a7970ee 2022-10-01 op To generate a temporary random password use
143 2a7970ee 2022-10-01 op .Bd -literal -offset indent
144 2a7970ee 2022-10-01 op $ plass gen -n
145 2a7970ee 2022-10-01 op .Ed
146 2a7970ee 2022-10-01 op .Sh SEE ALSO
147 2a7970ee 2022-10-01 op .Xr got 1 ,
148 2a7970ee 2022-10-01 op .Xr gpg 1 ,
149 2a7970ee 2022-10-01 op .Xr pass 1
150 2a7970ee 2022-10-01 op .Sh HISTORY
151 e346be82 2022-06-29 op .Nm
152 e346be82 2022-06-29 op was heavily influenced by
153 e346be82 2022-06-29 op .Xr pass 1
154 2a7970ee 2022-10-01 op in the design, but it's a different implementation that prioritizes ease
155 2a7970ee 2022-10-01 op of use and composability.
156 e346be82 2022-06-29 op .Sh AUTHORS
157 e346be82 2022-06-29 op .An -nosplit
158 e346be82 2022-06-29 op The
159 e346be82 2022-06-29 op .Nm
160 e346be82 2022-06-29 op utility was written by
161 e346be82 2022-06-29 op .An Omar Polo Aq Mt op@omarpolo.com .
162 e346be82 2022-06-29 op .Sh CAVEATS
163 e346be82 2022-06-29 op .Nm
164 e346be82 2022-06-29 op .Cm find
165 e346be82 2022-06-29 op output format isn't designed to handle files containing newlines.
166 e346be82 2022-06-29 op Use
167 e346be82 2022-06-29 op .Xr find 1
168 e346be82 2022-06-29 op .Fl print0
169 e346be82 2022-06-29 op or similar if it's a concern.
170 e346be82 2022-06-29 op .Pp
171 2a7970ee 2022-10-01 op .Nm
172 2a7970ee 2022-10-01 op .Cm mv
173 2a7970ee 2022-10-01 op is not able to move directory trees, only file entries.
174 2a7970ee 2022-10-01 op .Pp
175 e346be82 2022-06-29 op There isn't a
176 e346be82 2022-06-29 op .Cm init
177 e346be82 2022-06-29 op sub-command, the store initialization must be performed manually.