1 e346be82 2022-06-29 op .\" Copyright (c) 2021, 2022 Omar Polo <op@omarpolo.com>
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.
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 b3b555d9 2022-10-05 op .Dd October 5, 2022
19 e346be82 2022-06-29 op .Nd manage passwords
24 5a0f0861 2022-09-09 op .Op Ar argument ...
25 e346be82 2022-06-29 op .Sh DESCRIPTION
27 e346be82 2022-06-29 op is a simple password manager.
28 2a7970ee 2022-10-01 op Passwords are stored as a directory tree where every password is a
29 2a7970ee 2022-10-01 op file encrypted with
32 2a7970ee 2022-10-01 op A password store is a
34 2a7970ee 2022-10-01 op repository with a worktree checked out at
35 2a7970ee 2022-10-01 op .Pa ~/.password-store
36 2a7970ee 2022-10-01 op .Pq or Ev PLASS_STORE .
37 2a7970ee 2022-10-01 op The only restriction is that a special file called
39 2a7970ee 2022-10-01 op containing the GPG recipient must exist in the root of the directory tree
42 2a7970ee 2022-10-01 op commands to work.
44 e346be82 2022-06-29 op Password entries can be referenced using the path relative to the
45 e346be82 2022-06-29 op store directory.
46 2a7970ee 2022-10-01 op The file extension
51 b3b555d9 2022-10-05 op provides global and command-specific options.
52 b3b555d9 2022-10-05 op Global options must precede the command name, and are as follows:
53 b3b555d9 2022-10-05 op .Bl -tag -width Ds
55 b3b555d9 2022-10-05 op Display usage information and exit immediately.
58 e346be82 2022-06-29 op The following commands are available:
59 e346be82 2022-06-29 op .Bl -tag -width Ds
60 e346be82 2022-06-29 op .It Cm cat Ar entries ...
61 2a7970ee 2022-10-01 op Decrypt and print the content of
63 5a0f0861 2022-09-09 op in the given order.
64 e346be82 2022-06-29 op .It Cm find Op Ar pattern
65 2a7970ee 2022-10-01 op Print the entries of the store one per line, optionally filtered by
67 2a7970ee 2022-10-01 op .It Cm gen Oo Fl nq Oc Oo Fl c Ar chars Oc Oo Fl l Ar length Oc Ar entry
68 e346be82 2022-06-29 op Generate and persist a password for the given
72 e346be82 2022-06-29 op can be used to control the characters allowed in the password
75 e346be82 2022-06-29 op i.e. all the printable ASCII characters)
79 e346be82 2022-06-29 op .Pq 32 by default .
82 2a7970ee 2022-10-01 op flag is provided, print the generated password.
85 8bd06def 2022-10-01 op flag is given the password won't be persisted and the
87 8bd06def 2022-10-01 op argument is optional.
88 e346be82 2022-06-29 op .It Cm mv Ar from Ar to
89 e346be82 2022-06-29 op Rename a password entry, doesn't work with directories.
91 2a7970ee 2022-10-01 op must exist and
94 e346be82 2022-06-29 op .It Cm rm Ar entries ...
95 e346be82 2022-06-29 op Remove the given
97 e346be82 2022-06-29 op from the store.
98 e346be82 2022-06-29 op .It Cm tee Oo Fl q Oc Ar entry
99 78859d14 2022-10-20 op Persist the data read from standard input into the store under the given
101 5a0f0861 2022-09-09 op name and the print it again on the standard output unless the
103 5a0f0861 2022-09-09 op option is given.
105 e346be82 2022-06-29 op .Sh ENVIRONMENT
106 e346be82 2022-06-29 op .Bl -tag -width Ds
107 e346be82 2022-06-29 op .It Ev PLASS_CHARS
108 e346be82 2022-06-29 op default range of characters to use to generate passwords.
109 e346be82 2022-06-29 op .It Ev PLASS_GOT
113 e346be82 2022-06-29 op .It Ev PLASS_GPG
117 e346be82 2022-06-29 op .It Ev PLASS_LENGTH
118 e346be82 2022-06-29 op Default length for the generated passwords.
119 e346be82 2022-06-29 op .It Ev PLASS_STORE
120 e346be82 2022-06-29 op Path to the password store directory tree.
123 e346be82 2022-06-29 op .Bl -tag -width Ds
124 e346be82 2022-06-29 op .It Pa ~/.password-store
125 e346be82 2022-06-29 op Password store used by default.
126 e346be82 2022-06-29 op .It Pa ~/.password-store/.gpg-id
127 2a7970ee 2022-10-01 op File containing the GPG recipient used to encrypt the passwords.
129 254b1ceb 2022-10-02 op .Sh EXIT STATUS
132 2a7970ee 2022-10-01 op A got repository and password store can be initialized as follows:
133 2a7970ee 2022-10-01 op .Bd -literal -offset indent
134 2a7970ee 2022-10-01 op $ mkdir ~/.password-store
135 2a7970ee 2022-10-01 op $ echo foo@example.com > ~/.password-store/.gpg-id
136 2a7970ee 2022-10-01 op $ gotadmin init ~/git/pass.git
137 2a7970ee 2022-10-01 op $ got import -r ~/git/pass.git -m 'initial import' ~/.password-store
138 2a7970ee 2022-10-01 op $ got checkout -E ~/git/pass.git ~/.password-store
143 2a7970ee 2022-10-01 op for more information.
145 2a7970ee 2022-10-01 op To migrate from
148 2a7970ee 2022-10-01 op .Pa ~/.password-store
149 2a7970ee 2022-10-01 op and check out it again using
152 2a7970ee 2022-10-01 op To generate a temporary random password use
153 2a7970ee 2022-10-01 op .Bd -literal -offset indent
154 2a7970ee 2022-10-01 op $ plass gen -n
157 5ed185dd 2022-10-02 op Display the entries matching
159 5ed185dd 2022-10-02 op arranged comfortably for reading in a terminal window:
160 5ed185dd 2022-10-02 op .Bd -literal -offset indent
161 5ed185dd 2022-10-02 op $ plass find key | rs
169 e346be82 2022-06-29 op was heavily influenced by
171 2a7970ee 2022-10-01 op in the design, but it's a different implementation that prioritizes ease
172 2a7970ee 2022-10-01 op of use and composability.
177 e346be82 2022-06-29 op utility was written by
178 e346be82 2022-06-29 op .An Omar Polo Aq Mt op@omarpolo.com .
182 e346be82 2022-06-29 op output format isn't designed to handle files containing newlines.
186 e346be82 2022-06-29 op or similar if it's a concern.
190 2a7970ee 2022-10-01 op is not able to move directory trees, only file entries.
192 e346be82 2022-06-29 op There isn't a
194 e346be82 2022-06-29 op sub-command, the store initialization must be performed manually.