pashage.1 (11220B)
1 .Dd December 6, 2024 2 .Dt PASHAGE 1 3 .Os 4 .Sh NAME 5 .Nm pashage 6 .Nd simple and portable password store for the Unix shell 7 .Sh SYNOPSIS 8 .Nm 9 .Op Ar COMMAND 10 .Op Ar OPTIONS 11 .Op Ar ARGS 12 .Sh DESCRIPTION 13 .Nm 14 is a 15 .Em password manager , 16 which means it manages a database of encrypted secrets, including encrypting 17 externally-provided new secrets, generating and encrypting random strings, and 18 decrypting and displaying stored secrets. 19 .Pp 20 It aims to be simple and composable, but its reliance on Unix philosophy 21 and customs might make steep learning curve for users outside of this 22 culture. 23 .Pp 24 The 25 .Nm 26 utility provides commands for query and management of the password store. 27 When no command is specified, 28 .Cm list 29 or 30 .Cm show 31 is implicitly assumed. 32 .Pp 33 The database is optionally versioned using 34 .Xr git 1 35 to help with history audit and synchronization. 36 It should be noted that this prevents re-encryption from erasing old 37 cyphertext, leaving the secret vulnerable to compromised encryption keys. 38 .Pp 39 The cryptography is done by 40 .Xr age 1 41 external command. 42 It decrypts using the 43 .Em identity 44 file given in the environment, and crypts using a list of 45 .Em recipients 46 per subfolder, defaulting to the parent 47 .Em recipient 48 list or the 49 .Em identity . 50 .Sh COMMANDS 51 .Ss copy 52 .Nm 53 .Cm copy 54 .Op Fl e,--reencrypt | Fl i,--interactive | Fl k,--keep 55 .Op Fl f,--force 56 .Ar old-path ... new-path 57 .Pp 58 This subcommand copies secrets and recursively copies subfolders, 59 using the same positional argument scheme as 60 .Xr cp 1 . 61 By default it asks before overwriting an existing secret and it re-encrypts 62 the secret when the destination has a different 63 .Em recipient 64 list. 65 .Pp 66 The options are as follows: 67 .Bl -tag -compact -width \-i,--interactive 68 .It Fl e,--reencrypt 69 always re-encrypt secrets 70 .It Fl f,--force 71 overwrite existing secrets without asking 72 .It Fl i,--interactive 73 asks whether to re-encrypt or not for each secret 74 .It Fl k,--keep 75 never re-encrypt secrets 76 .El 77 .Ss delete 78 .Nm 79 .Cm delete 80 .Op Fl r,--recursive 81 .Op Fl f,--force 82 .Ar pass-name 83 .Ar ... 84 .Pp 85 This subcommand deletes secrets from the database. 86 By default it skips subfolders and asks for confirmation for each secret. 87 The options are as follows: 88 .Bl -tag -compact -width \-r,--recursive 89 .It Fl f,--force 90 delete without asking for confirmation 91 .It Fl r,--recursive 92 recursively delete all secrets in given subfolders 93 .El 94 .Ss edit 95 .Nm 96 .Cm edit 97 .Ar pass-name 98 .Ar ... 99 .Pp 100 This subcommand starts an interactive editor to update the secrets. 101 .Ss find 102 .Nm 103 .Cm find 104 .Op Ar GREP_OPTIONS 105 .Ar regex 106 .Pp 107 This subcommand lists as a tree the secrets whose name match the given 108 regular expression, using the corresponding 109 .Xr grep 1 110 options. 111 .Ss generate 112 .Nm 113 .Cm generate 114 .Op Fl n,--no-symbols 115 .Op Fl c,--clip | Fl q,--qrcode 116 .Op Fl i,--in-place | Fl f,--force 117 .Op Fl m,--multiline 118 .Op Fl t,--try 119 .Ar pass-name 120 .Op Ar pass-length Op Ar character-set 121 .Pp 122 This subcommand generates a new secret from 123 .Pa /dev/urandom , 124 stores it in the database, and by default displays it on the standard output 125 and asks 126 for confirmation before overwriting an existing secret. 127 .Pp 128 The options are as follows: 129 .Bl -tag -compact -width \-n,--no-symbols 130 .It Fl c,--clip 131 paste the secret into the clipboard instead of using the standard output 132 .It Fl f,--force 133 replace existing secrets without asking 134 .It Fl i,--in-place 135 when the secret already exists, replace only its first line and re-use the 136 following lines 137 .It Fl m,--multiline 138 read lines from standard input append after the generated data into the secret 139 file 140 .It Fl n,--no-symbols 141 generate a secret using only alphanumeric characters 142 .It Fl q,--qrcode 143 display the secret as a QR-code instead of using the standard output 144 .It Fl t,--try 145 display the secret and ask for confirmation before storing it into the database 146 .El 147 .Ss git 148 .Nm 149 .Cm git git-command-args ... 150 .Pp 151 This subcommand invokes 152 .Xr git 1 153 in the database repository. 154 Only 155 .Cm git init 156 and 157 .Cm git clone 158 are accepted when there is no underlying repository. 159 .Ss gitconfig 160 .Nm 161 .Cm gitconfig 162 .Pp 163 This subcommand configures the underlying repository to automatically 164 decrypt secrets to display differences. 165 .Ss grep 166 .Nm 167 .Cm grep 168 .Op Ar GREP_OPTIONS 169 .Ar search-regex 170 .Pp 171 This subcommand successively decrypts all the secrets in the store and 172 filter them through 173 .Xr grep 1 174 using the given options, and outputs all the matching lines and the 175 corresponding secret. 176 .Ss help 177 .Nm 178 .Cm help 179 .Pp 180 This subcommand displays on the standard output the version and help text, 181 including all subcommands and flags and a brief description. 182 .Ss init 183 .Nm 184 .Cm init 185 .Op Fl i,--interactive | Fl k,--keep 186 .Op Fl p,--path Ar subfolder 187 .Ar age-recipient 188 .Ar ... 189 .Pp 190 This subcommand initializes an age 191 .Em recipient 192 list, by default of the root of the password store, and re-encrypts all the 193 affected secrets. 194 When the 195 .Ar age-recipient 196 list is a single empty string, the 197 .Em recipient 198 list is instead removed, falling back to a parent 199 .Em recipient 200 list or ultimately to the age 201 .Em identity . 202 .Pp 203 The options are as follows: 204 .Bl -tag -compact -width \-i,--interactive 205 .It Fl i,--interactive 206 ask for each secret whether to re-encrypt it or not 207 .It Fl k,--keep 208 do not re-encrypt any secret 209 .It Fl p,--path 210 operate on the 211 .Em recipient 212 list in the given subfolder instead of the root of the password store 213 .El 214 .Ss insert 215 .Nm 216 .Cm insert 217 .Op Fl e,--echo | Fl m,--multiline 218 .Op Fl f,--force 219 .Ar pass-name 220 .Ar ... 221 .Pp 222 This subcommand adds new secrets in the database, using the provided data 223 from the standard input. 224 By default asks before overwriting an existing secret, and it reads a single 225 secret line after turning off the console echo, and reads it a second time for 226 confirmation. 227 .Pp 228 The options are as follows: 229 .Bl -tag -compact -width \-m,--multiline 230 .It Fl e,--echo 231 read a single line once without manipulating the standard input 232 .It Fl m,--multiline 233 an arbitrary amount of lines from the standard input, without trying to 234 manipulate the console, until the end of input or a blank line is entered 235 .It Fl f,--force 236 overwrite an existing secret without asking 237 .El 238 .Ss list 239 .Nm 240 .Op Cm list 241 .Op Ar subfolder ... 242 .Pp 243 This subcommand displays the given subfolders as a tree, or the whole store 244 when no subfolder is specified. 245 .Pp 246 Note that when a secret is given instead of a subfolder, the 247 .Cm show 248 command will be used instead, without any warning or error. 249 .Ss move 250 .Nm 251 .Cm move 252 .Op Fl e,--reencrypt | Fl i,--interactive | Fl k,--keep 253 .Op Fl f,--force 254 .Ar old-path ... new-path 255 .Pp 256 This subcommand moves or renames secrets and subfolders recursively, 257 using the same positional argument scheme as 258 .Xr mv 1 . 259 By default it asks before overwriting an existing secret and it re-encrypts 260 the secret when the destination has a different 261 .Em recipient 262 list. 263 .Pp 264 The options are as follows: 265 .Bl -tag -compact -width \-i,--interactive 266 .It Fl e,--reencrypt 267 always re-encrypt secrets 268 .It Fl f,--force 269 overwrite existing secrets without asking 270 .It Fl i,--interactive 271 asks whether to re-encrypt or not for each secret 272 .It Fl k,--keep 273 never re-encrypt secrets 274 .El 275 .Ss random 276 .Nm 277 .Cm random 278 .Op Ar pass-length Op Ar character-set 279 .Pp 280 This subcommand generates a new secret, like the 281 .Cm generate 282 subcommand, then directly displays on the standard output without storing it. 283 .Ss reencrypt 284 .Nm 285 .Cm reencrypt 286 .Op Fl i,--interactive 287 .Ar pass-name|subfolder 288 .Ar ... 289 .Pp 290 This subcommand re-encrypts in place the given secrets, and all the secrets 291 recursively in the given subfolders. 292 .Pp 293 The options are as follows: 294 .Bl -tag -compact -width \-i,--interactive 295 .It Fl i,--interactive 296 asks whether to re-encrypt or not for each secret 297 .El 298 .Ss show 299 .Nm 300 .Op Cm show 301 .Oo 302 .Fl c,--clip Op Ar line-number | 303 .Fl q,--qrcode Ar line-number 304 .Oc 305 .Ar pass-name 306 .Ar ... 307 .Pp 308 This subcommand decrypts the given secrets and by default displays the 309 whole text on the standard output. 310 .Pp 311 Note that when a subfolder is given instead of a secret, the 312 .Cm list 313 command will be used instead, without any warning or error. 314 .Pp 315 The options are as follows: 316 .Bl -tag -compact -width \-q,--qrcode 317 .It Fl c,--clip 318 paste the given line (by default the first line) of the secret into the 319 clipboard instead of using the standard output 320 .It Fl q,--qrcode 321 display the given line (by default the first line) of the secret as a QR-code 322 instead of using the standard output 323 .El 324 .Ss version 325 .Nm 326 .Cm version 327 .Pp 328 This subcommand displays on the standard output the version and author 329 list. 330 .Sh ENVIRONMENT 331 The following environment variables affect the execution of 332 .Nm : 333 .\" The largest symbol is actually PASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS 334 .\" but that compresses the second columns way too much. 335 .Bl -tag -width XXXXXXXX 336 .It Ev CLICOLOR 337 when set to a non-empty value, use ANSI escape sequences to color the output 338 .It Ev EDITOR 339 editor command to use instead of 340 .Xr vi 1 341 when 342 .Ev VISUAL 343 is not set 344 .It Ev LC_CTYPE 345 when it contains 346 .Qq UTF , 347 the tree is displayed using Unicode graphic characters instead of ASCII 348 .It Ev PASHAGE_AGE 349 external command to use instead of 350 .Xr age 1 351 .It Ev PASHAGE_DIR 352 database directory to use instead of 353 .Pa ~/.passage/store 354 .It Ev PASHAGE_IDENTITIES_FILE 355 .Em identity 356 file to use instead of 357 .Pa ~/.passage/identities 358 .It Ev PASSAGE_AGE 359 external command to use instead of 360 .Xr age 1 361 when 362 .Ev PASHAGE_AGE 363 is unset 364 .It Ev PASSAGE_DIR 365 database directory to use instead of 366 .Pa ~/.passage/store 367 when 368 .Ev PASHAGE_DIR 369 is unset 370 .It Ev PASSAGE_IDENTITIES_FILE 371 .Em identity 372 file to use instead of 373 .Pa ~/.passage/identities 374 when 375 .Ev PASHAGE_IDENTITIES_FILE 376 is unset 377 .It Ev PASSWORD_STORE_CHARACTER_SET_NO_SYMBOLS 378 default character set to use with 379 .Xr tr 1 380 when 381 .Fl n 382 is specified, instead of 383 .Qq [:alnum:] 384 .It Ev PASSWORD_STORE_CHARACTER_SET 385 character set to use with 386 .Xr tr 1 387 when no character set requirement is specified for the 388 .Cm generate 389 or 390 .Cm random 391 commands, instead of 392 .Qq [:punct:][:alnum:] 393 .It Ev PASSWORD_STORE_CLIP_TIME 394 number of second before clearing the clipboard when 395 .Fl c 396 is used, instead of 45 397 .It Ev PASSWORD_STORE_DIR 398 database directory to use instead of 399 .Pa ~/.passage/store 400 when both 401 .Ev PASHAGE_DIR 402 and 403 .Ev PASSAGE_DIR 404 are unset 405 .It Ev PASSWORD_STORE_GENERATED_LENGTH 406 number of characters in the generated secret when not explicitly given, 407 instead of 25 408 .It Ev PASSWORD_STORE_X_SELECTION 409 selection to use when 410 .Fl c 411 and 412 .Xr xclip 1 413 are used, instead of 414 .Qq clipboard 415 .It Ev TMPDIR 416 temporary directory for the decrypted file to use instead of 417 .Pa /tmp 418 when 419 .Pa /dev/shm 420 is not available 421 .It Ev VISUAL 422 editor command to use instead of 423 .Xr vi 1 424 .El 425 .Sh FILES 426 Most paths used by 427 .Nm 428 can be configured through environment variables. 429 Here are the defaults: 430 .Bl -tag -width XXXXXXXX 431 .It Pa ~/.passage/identities 432 .Xr age 1 433 .Em identities 434 to use for decryption 435 .It Pa ~/.passage/store/ 436 Root directory of the password store 437 .It Pa /dev/shm/ 438 Temporary directory 439 .Pq when available 440 .It Pa /dev/urandom 441 Source of entropy 442 .It Pa /tmp 443 Temporary directory 444 .Po 445 when 446 .Pa /dev/sdm 447 is not available 448 .Pc 449 .El 450 .Sh SEE ALSO 451 .Xr age 1 , 452 .Xr git 1 , 453 .Xr tr 1 , 454 .Xr vi 1 , 455 .Xr xclip 1 . 456 .Sh AUTHORS 457 .Nm 458 was written by 459 .An Natasha Kerensikova , 460 based on earlier work by: 461 .An Jason A. Donenfeld 462 .Pq password-store 463 .An Filippo Valsorda 464 .Pq passage 465 .An Dylan Araps 466 .Pq pash