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 June 29, 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 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.
75 .It Cm got Ar arguments
76 Execute
77 .Xr got 1
78 in the password store directory with the given
79 .Ar arguments .
80 .It Cm mv Ar from Ar to
81 Rename a password entry, doesn't work with directories.
82 .Ar from
83 must exists and
84 .Ar to
85 mustn't.
86 .It Cm rm Ar entries ...
87 Remove the given
88 .Ar entries
89 from the store.
90 .It Cm tee Oo Fl q Oc Ar entry
91 Prompt for a password and persist it into the store under the given
92 .Ar entry
93 name and the print it again on the standard output unless the
94 .Fl q
95 option is given.
96 .It Cm tog Ar arguments ...
97 Execute
98 .Xr tog 1
99 in the password store directory with the given
100 .Ar arguments .
101 .El
102 .Sh CREATING A PASSWORD STORE
103 A password store is just a normal
104 .Xr got 1
105 repository with a worktree checkout out in
106 .Pa ~/.password-store
107 .Pq or at Ev PLASS_STORE .
108 The only restriction is that a special file called
109 .Pa .gpg-id
110 must exist in the root of the work tree for most
111 .Nm
112 commands to work.
113 .Pp
114 For example, a got repository and password store can be initialized as
115 follows:
116 .Bd -literal -offset indent
117 $ mkdir ~/.password-store
118 $ echo foo@example.com > ~/.password-store/.gpg-id
119 $ gotadmin init ~/git/pass.git
120 $ got import -r ~/git/pass.git -m 'initial import' ~/.password-store
121 $ got checkout -E ~/git/pass.git ~/.password-store
122 .Ed
123 .Pp
124 see
125 .Xr got 1
126 for more information.
127 .Pp
128 Otherwise, if a repository already exists, a password store can be
129 checked out as:
130 .Bd -literal -offset indent
131 $ got checkout ~/git/pass.git ~/.password-store
132 .Ed
133 .Pp
134 To migrate from
135 .Xr pass 1 ,
136 just delete
137 .Pa ~/.password-store
138 and check out it again using
139 .Xr got 1 .
140 .Sh ENVIRONMENT
141 .Bl -tag -width Ds
142 .It Ev PLASS_CHARS
143 default range of characters to use to generate passwords.
144 .It Ev PLASS_GOT
145 Path to the
146 .Xr got 1
147 executable.
148 .It Ev PLASS_GPG
149 Path to the
150 .Xr gpg 1
151 executable.
152 .It Ev PLASS_LENGTH
153 Default length for the generated passwords.
154 .It Ev PLASS_STORE
155 Path to the password store directory tree.
156 .It Ev PLASS_TOG
157 Path to the
158 .Xr tog 1
159 executable.
160 .El
161 .Sh FILES
162 .Bl -tag -width Ds
163 .It Pa ~/.password-store
164 Password store used by default.
165 .It Pa ~/.password-store/.gpg-id
166 File containing the gpg recipient used to encrypt the passwords.
167 .El
168 .Sh ACKNOWLEDGEMENTS
169 .Nm
170 was heavily influenced by
171 .Xr pass 1
172 in the design, but it's a completely different implementation with
173 different tools involved.
174 .Sh AUTHORS
175 .An -nosplit
176 The
177 .Nm
178 utility was written by
179 .An Omar Polo Aq Mt op@omarpolo.com .
180 .Sh CAVEATS
181 .Nm
182 .Cm find
183 output format isn't designed to handle files containing newlines.
184 Use
185 .Xr find 1
186 .Fl print0
187 or similar if it's a concern.
188 .Pp
189 There isn't a
190 .Cm init
191 sub-command, the store initialization must be performed manually.