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