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 .Oo
24 .Cm command
25 .Ar argument ...
26 .Oc
27 .Sh DESCRIPTION
28 .Nm
29 is a simple password manager.
30 It manages paswords store in a directory tree rooted at
31 .Pa ~/.password-store
32 .Pq or at Ev PLASS_STORE ,
33 where every password is a single file encrypted with
34 .Xr gpg2 1 .
35 .Pp
36 Password entries can be referenced using the path relative to the
37 store directory.
38 The extension
39 .Dq \&.gpg
40 is optional.
41 .Pp
42 The whole store is supposed to be managed by the
43 .Xr got 1
44 version control system.
45 .Pp
46 The following commands are available:
47 .Bl -tag -width Ds
48 .It Cm cat Ar entries ...
49 Decrypt and print the content of the given
50 .Ar entries .
51 .It Cm find Op Ar pattern
52 Print one per line all the entries of the store, optionally filtered
53 by the given
54 .Ar pattern .
55 .It Cm gen Oo Fl nq Oc Oo Fl c Ar chars Oc Oo Fl l Ar length Oc Ar entry
56 Generate and persist a password for the given
57 .Ar entry
58 in the store.
59 .Fl c
60 can be used to control the characters allowed in the password
61 (by default
62 .Dq !-~
63 i.e. all the printable ASCII characters)
64 and
65 .Fl l
66 the length
67 .Pq 32 by default .
68 Unless the
69 .Fl q
70 flag is provided,
71 .Nm
72 prints the generated password.
73 If the
74 .Fl n
75 flag is given, the password won't be persisted.
76 .It Cm got Ar arguments
77 Execute
78 .Xr got 1
79 in the password store directory with the given
80 .Ar arguments .
81 .It Cm mv Ar from Ar to
82 Rename a password entry, doesn't work with directories.
83 .Ar from
84 must exists and
85 .Ar to
86 mustn't.
87 .It Cm rm Ar entries ...
88 Remove the given
89 .Ar entries
90 from the store.
91 .It Cm tee Oo Fl q Oc Ar entry
92 Prompt for a password and persist it into the store under the given
93 .Ar entry
94 name and the print it again on the standard output.
95 If the
96 .Fl q
97 option is given, nothing is printed to standard output.
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 $ got 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 gpg2 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.