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 e346be82 2022-06-29 op .Dd June 29, 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 5a0f0861 2022-09-09 op It manages paswords stored in a directory tree rooted at
 29 e346be82 2022-06-29 op .Pa ~/.password-store
 30 e346be82 2022-06-29 op .Pq or at Ev PLASS_STORE ,
 31 e346be82 2022-06-29 op where every password is a single file encrypted with
 32 5a0f0861 2022-09-09 op .Xr gpg 1 .
 33 e346be82 2022-06-29 op .Pp
 34 e346be82 2022-06-29 op Password entries can be referenced using the path relative to the
 35 e346be82 2022-06-29 op store directory.
 36 e346be82 2022-06-29 op The extension
 37 e346be82 2022-06-29 op .Dq \&.gpg
 38 e346be82 2022-06-29 op is optional.
 39 e346be82 2022-06-29 op .Pp
 40 e346be82 2022-06-29 op The whole store is supposed to be managed by the
 41 e346be82 2022-06-29 op .Xr got 1
 42 e346be82 2022-06-29 op version control system.
 43 e346be82 2022-06-29 op .Pp
 44 e346be82 2022-06-29 op The following commands are available:
 45 e346be82 2022-06-29 op .Bl -tag -width Ds
 46 e346be82 2022-06-29 op .It Cm cat Ar entries ...
 47 e346be82 2022-06-29 op Decrypt and print the content of the given
 48 5a0f0861 2022-09-09 op .Ar entries
 49 5a0f0861 2022-09-09 op in the given order.
 50 e346be82 2022-06-29 op .It Cm find Op Ar pattern
 51 e346be82 2022-06-29 op Print one per line all the entries of the store, optionally filtered
 52 e346be82 2022-06-29 op by the given
 53 e346be82 2022-06-29 op .Ar pattern .
 54 e346be82 2022-06-29 op .It Cm gen Oo Fl nq Oc Oo Fl c Ar chars Oc Oo Fl l Ar length Oc Ar entry
 55 e346be82 2022-06-29 op Generate and persist a password for the given
 56 e346be82 2022-06-29 op .Ar entry
 57 e346be82 2022-06-29 op in the store.
 58 e346be82 2022-06-29 op .Fl c
 59 e346be82 2022-06-29 op can be used to control the characters allowed in the password
 60 e346be82 2022-06-29 op (by default
 61 e346be82 2022-06-29 op .Dq !-~
 62 e346be82 2022-06-29 op i.e. all the printable ASCII characters)
 63 e346be82 2022-06-29 op and
 64 e346be82 2022-06-29 op .Fl l
 65 e346be82 2022-06-29 op the length
 66 e346be82 2022-06-29 op .Pq 32 by default .
 67 e346be82 2022-06-29 op Unless the
 68 e346be82 2022-06-29 op .Fl q
 69 e346be82 2022-06-29 op flag is provided,
 70 e346be82 2022-06-29 op .Nm
 71 e346be82 2022-06-29 op prints the generated password.
 72 e346be82 2022-06-29 op If the
 73 e346be82 2022-06-29 op .Fl n
 74 e346be82 2022-06-29 op flag is given, the password won't be persisted.
 75 e346be82 2022-06-29 op .It Cm got Ar arguments
 76 e346be82 2022-06-29 op Execute
 77 e346be82 2022-06-29 op .Xr got 1
 78 e346be82 2022-06-29 op in the password store directory with the given
 79 e346be82 2022-06-29 op .Ar arguments .
 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 e346be82 2022-06-29 op must exists 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 .It Cm tog Ar arguments ...
 97 e346be82 2022-06-29 op Execute
 98 e346be82 2022-06-29 op .Xr tog 1
 99 e346be82 2022-06-29 op in the password store directory with the given
100 e346be82 2022-06-29 op .Ar arguments .
101 e346be82 2022-06-29 op .El
102 e346be82 2022-06-29 op .Sh CREATING A PASSWORD STORE
103 e346be82 2022-06-29 op A password store is just a normal
104 e346be82 2022-06-29 op .Xr got 1
105 e346be82 2022-06-29 op repository with a worktree checkout out in
106 e346be82 2022-06-29 op .Pa ~/.password-store
107 e346be82 2022-06-29 op .Pq or at Ev PLASS_STORE .
108 e346be82 2022-06-29 op The only restriction is that a special file called
109 e346be82 2022-06-29 op .Pa .gpg-id
110 e346be82 2022-06-29 op must exist in the root of the work tree for most
111 e346be82 2022-06-29 op .Nm
112 e346be82 2022-06-29 op commands to work.
113 e346be82 2022-06-29 op .Pp
114 e346be82 2022-06-29 op For example, a got repository and password store can be initialized as
115 e346be82 2022-06-29 op follows:
116 e346be82 2022-06-29 op .Bd -literal -offset indent
117 355fc9e0 2022-09-09 op $ mkdir ~/.password-store
118 355fc9e0 2022-09-09 op $ echo foo@example.com > ~/.password-store/.gpg-id
119 355fc9e0 2022-09-09 op $ gotadmin init ~/git/pass.git
120 355fc9e0 2022-09-09 op $ got import -r ~/git/pass.git -m 'initial import' ~/.password-store
121 e346be82 2022-06-29 op $ got checkout -E ~/git/pass.git ~/.password-store
122 e346be82 2022-06-29 op .Ed
123 e346be82 2022-06-29 op .Pp
124 e346be82 2022-06-29 op see
125 e346be82 2022-06-29 op .Xr got 1
126 e346be82 2022-06-29 op for more information.
127 e346be82 2022-06-29 op .Pp
128 e346be82 2022-06-29 op Otherwise, if a repository already exists, a password store can be
129 e346be82 2022-06-29 op checked out as:
130 e346be82 2022-06-29 op .Bd -literal -offset indent
131 e346be82 2022-06-29 op $ got checkout ~/git/pass.git ~/.password-store
132 e346be82 2022-06-29 op .Ed
133 e346be82 2022-06-29 op .Pp
134 e346be82 2022-06-29 op To migrate from
135 e346be82 2022-06-29 op .Xr pass 1 ,
136 e346be82 2022-06-29 op just delete
137 e346be82 2022-06-29 op .Pa ~/.password-store
138 e346be82 2022-06-29 op and check out it again using
139 e346be82 2022-06-29 op .Xr got 1 .
140 e346be82 2022-06-29 op .Sh ENVIRONMENT
141 e346be82 2022-06-29 op .Bl -tag -width Ds
142 e346be82 2022-06-29 op .It Ev PLASS_CHARS
143 e346be82 2022-06-29 op default range of characters to use to generate passwords.
144 e346be82 2022-06-29 op .It Ev PLASS_GOT
145 e346be82 2022-06-29 op Path to the
146 e346be82 2022-06-29 op .Xr got 1
147 e346be82 2022-06-29 op executable.
148 e346be82 2022-06-29 op .It Ev PLASS_GPG
149 e346be82 2022-06-29 op Path to the
150 5a0f0861 2022-09-09 op .Xr gpg 1
151 e346be82 2022-06-29 op executable.
152 e346be82 2022-06-29 op .It Ev PLASS_LENGTH
153 e346be82 2022-06-29 op Default length for the generated passwords.
154 e346be82 2022-06-29 op .It Ev PLASS_STORE
155 e346be82 2022-06-29 op Path to the password store directory tree.
156 e346be82 2022-06-29 op .It Ev PLASS_TOG
157 e346be82 2022-06-29 op Path to the
158 e346be82 2022-06-29 op .Xr tog 1
159 e346be82 2022-06-29 op executable.
160 e346be82 2022-06-29 op .El
161 e346be82 2022-06-29 op .Sh FILES
162 e346be82 2022-06-29 op .Bl -tag -width Ds
163 e346be82 2022-06-29 op .It Pa ~/.password-store
164 e346be82 2022-06-29 op Password store used by default.
165 e346be82 2022-06-29 op .It Pa ~/.password-store/.gpg-id
166 e346be82 2022-06-29 op File containing the gpg recipient used to encrypt the passwords.
167 e346be82 2022-06-29 op .El
168 e346be82 2022-06-29 op .Sh ACKNOWLEDGEMENTS
169 e346be82 2022-06-29 op .Nm
170 e346be82 2022-06-29 op was heavily influenced by
171 e346be82 2022-06-29 op .Xr pass 1
172 e346be82 2022-06-29 op in the design, but it's a completely different implementation with
173 e346be82 2022-06-29 op different tools involved.
174 e346be82 2022-06-29 op .Sh AUTHORS
175 e346be82 2022-06-29 op .An -nosplit
176 e346be82 2022-06-29 op The
177 e346be82 2022-06-29 op .Nm
178 e346be82 2022-06-29 op utility was written by
179 e346be82 2022-06-29 op .An Omar Polo Aq Mt op@omarpolo.com .
180 e346be82 2022-06-29 op .Sh CAVEATS
181 e346be82 2022-06-29 op .Nm
182 e346be82 2022-06-29 op .Cm find
183 e346be82 2022-06-29 op output format isn't designed to handle files containing newlines.
184 e346be82 2022-06-29 op Use
185 e346be82 2022-06-29 op .Xr find 1
186 e346be82 2022-06-29 op .Fl print0
187 e346be82 2022-06-29 op or similar if it's a concern.
188 e346be82 2022-06-29 op .Pp
189 e346be82 2022-06-29 op There isn't a
190 e346be82 2022-06-29 op .Cm init
191 e346be82 2022-06-29 op sub-command, the store initialization must be performed manually.