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