awiteb/lprs
1
Fork 0
Code Issues 2 Pull requests Releases 3 Activity Actions

feat: Lprs docs #49

Merged
awiteb merged 4 commits from awiteb/lprs-book into master 2024-05-17 00:19:38 +02:00 AGit
Conversation 0 Commits 4 Files changed 16 +627
14 changed files with 627 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit fa4fb96a40 - Show all commits

15
docs/SUMMARY.md Normal file
View file

@ -0,0 +1,15 @@
# Lprs Documentation
- [Introduction](introduction.md)
- [Installation](installation.md)
- [Command line usage](commands/README.md)
- [Adding a vault](commands/add.md)
- [Removing a vault](commands/remove.md)
- [Editing a vault](commands/edit.md)
- [Getting a vault](commands/get.md)
- [Listing all vaults](commands/list.md)
- [Clening the vaults](commands/clean.md)
- [Generating a password](commands/gen.md)
- [Importing and exporting vaults](commands/import-export.md)
- [Changing the master password](commands/change-master-password.md)
- [Auto completion](commands/auto-completion.md)

46
docs/commands/README.md Normal file
View file

@ -0,0 +1,46 @@
# Command line usage
This section provides a reference for the various commands and options that are
available in the `lprs` command line tool, and how to use them.
But before we dive into the commands, let's take a look at the `lprs` main
options, which are available for all commands.
```
Options:
-f, --vaults-file <VAULTS_FILE> The vaults json file
-v, --verbose Show the logs in the stdout
-m, --master-password <MASTER_PASSWORD> The master password, or you will prompt it
-h, --help Print help
-V, --version Print version
```
As you can see, the `lprs` command line tool has a few options that are
available for all commands, which are:
- `-f, --vaults-file <VAULTS_FILE>`: The vaults json file, this is the file
where the vaults are stored. By default, the vaults are stored in the
program's directory, in a directory called `lprs` and the file called
`vaults.lprs`.
- `-v, --verbose`: Show the logs in the stdout, this option is useful for
debugging purposes.
- `-m, --master-password <MASTER_PASSWORD>`: The master password, this is the
password that is used to encrypt and decrypt the vaults, usful for scripting
purposes, otherwise you will be prompted for the master password (which is
better for security reasons)
Now let's take a look at the available commands and how to use them.
- [Adding a vault](commands/add.md)
- [Removing a vault](commands/remove.md)
- [Editing a vault](commands/edit.md)
- [Getting a vault](commands/get.md)
- [Listing all vaults](commands/list.md)
- [Clening the vaults](commands/clean.md)
- [Generating a password](commands/generate-password.md)
- [Importing and exporting vaults](commands/import-export.md)
- [Changing the master password](commands/change-master-password.md)
- [Auto completion](commands/auto-completion.md)
## Donations
You can support the development of my projects by donating me, check out my profile at [git.4rs.nl](https://git.4rs.nl/awiteb#donations)

92
docs/commands/add.md Normal file
View file

@ -0,0 +1,92 @@
# Adding a vault
## Usage
```
Usage: lprs add [OPTIONS] <NAME>
Arguments:
<NAME>
The name of the vault
Options:
-u, --username <USERNAME>
The username
-s, --service <SERVICE>
The service name. e.g the website url
-n, --note <NOTE>
Add a note to the vault
--totp-hash <HASH_FUNCTION>
The TOTP hash function
[default: sha1]
Possible values:
- sha1: Sha1 hash function
- sha256: Sha256 hash function
- sha512: Sha512 hash function
-p, --password [<PASSWORD>]
The password, if there is no value you will prompt it
-t, --totp-secret [<TOTP_SECRET>]
The TOTP secret, if there is no value you will prompt it
-c, --custom <KEY=VALUE>
Add a custom field to the vault
-f, --force
Force add, will not return error if there is a problem with the args.
For example, duplication in the custom fields and try to adding empty vault
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
```
So, to add a vault you need to provide a name for the vault, and you can provide
a username, service name, note, password, TOTP secret, and custom fields.
For secrets like the password and TOTP secret, you can provide them as arguments
or you will be prompted for them.
### Custom fields
You can't add a custom field prefixed with `.lprsfield.` because it's reserved
for backwards compatibility.
## Examples
Add a vault:
```sh
lprs add my-vault1 -u my-username -s my-service -n 'My super secret note' \
-p my-password -t 'JFWG65TFKJ2XG5BO' \
-c key1=value1 -c key2=value2
```
Add a vault with a username and a password, but prompt for the password:
```sh
# -p without a value will prompt you for the password
lprs add my-vault2 -u my-username -p
```
Add a vault with a username, a password, and custom fields:
```sh
# The password will be prompted
lprs add my-vault3 -u my-username -p \
-c key1=value1 \
-c 'long key'='long value'
```
## Notes
- You must provide a name for the vault and at least one of the following:
username, password, TOTP secret, or custom fields.
- If you provide a password or TOTP secret as an argument, it will be visible in
the shell history.
- You can use existing vault names, and it will not be overwritten, so if you
edit, get, or remove a vault by its name, it will be the first one found, so
be careful with the names.

25
docs/commands/auto-completion.md Normal file
View file

@ -0,0 +1,25 @@
# Auto completion
## Usage
```
Usage: lprs completion <SHELL>
Arguments:
<SHELL> Shell to generate completion for [possible values: bash, elvish, fish, powershell, zsh]
Options:
-h, --help Print help
```
The `completion` command generates completion scripts for the specified shell. The output is written to `stdout`, so you can redirect it to a file and source it in your shell configuration file.
## How to use
| Shell | Command to generate completion script | Command location (the file to write the command in) |
|------------|---------------------------------------|----------------------------------------------------|
| Bash | `eval "$(lprs completion bash)"` | `~/.bashrc` |
| Elvish | `eval (lprs completion elvish \| slurp)` | `~/.elvish/rc.elv` |
| Fish | `lprs completion fish \| source` | `~/.config/fish/config.fish` |
| Powershell | `Invoke-Expression (& { (lprs completion powershell \| Out-String) })` | run `echo $PROFILE` |
| Zsh | `eval "$(lprs completion zsh)"` | `~/.zshrc` |

3
docs/commands/change-master-password.md Normal file
View file

@ -0,0 +1,3 @@
# Changing the master password
## Usage

19
docs/commands/clean.md Normal file
View file

@ -0,0 +1,19 @@
# Clening the vaults
## Usage
```
Usage: lprs clean
Options:
-h, --help Print help
-V, --version Print version
```
Is simple, just run `lprs clean` and the vaults file will be cleaned, removing
all the vaults from it.
## Notes
- You can't undo this action, so be careful when using it.
- You can specify the vaults file by using the `--vaults-file` option. [See main
lprs options](./index.html).

85
docs/commands/edit.md Normal file
View file

@ -0,0 +1,85 @@
# Editing a vault
## Usage
```
Usage: lprs edit [OPTIONS] <INDEX-or-NAME>
Arguments:
<INDEX-or-NAME>
The vault to edit, index or name
Options:
-n, --name <NAME>
The new vault name
-u, --username <USERNAME>
The new vault username
-p, --password [<PASSWORD>]
The new password, if there is no value for it you will prompt it
-s, --service <SERVICE>
The new vault service
-o, --note <NOTE>
The new vault note
-t, --totp-secret [<TOTP_SECRET>]
The TOTP secret, if there is no value you will prompt it
-c, --custom <KEY=VALUE>
The custom field, make its value empty to delete it
If the custom field not exist will created it, if it's will update it
-f, --force
Force edit, will not return error if there is a problem with the args.
For example, duplication in the custom fields and try to editing nothing
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
```
To edit a vault you need to provide the index or the name of the vault. If you
provide the index, the vault will be edited by its index, if you provide the
name, the vault will be edited the first vault with the given name.
You can edit the vault name, username, password, service, note, TOTP secret, and
custom fields.
For secrets like the password and TOTP secret, you can provide them as arguments
or you will be prompted for them.
## Custom fields
If you want to add a custom field to the vault, you can use the `-c, --custom`
option, and provide the key-value pair. If you want to delete a custom field,
you can provide the key with an empty value, e.g. `-c key=""`. If the custom
field not exist it will be created, if it's exist it will be updated.
You can't add a new custom field prefixed with `.lprsfield.` because it's
reserved for backwards compatibility.
## Examples
Edit a vault by its index:
```sh
lprs edit 1 -n new-vault-name -u new-username -p new-password -s new-service -o new-note -t new-totp-secret -c key1=value1 -c key2=value2
```
Edit a vault password by its name:
```sh
# You will be prompted for the new password
lprs edit my-vault -p
```
Remove a custom field from a vault by its name:
```sh
lprs edit my-vault -c key1=""
```
## Notes
- The index is one-based (the first vault is 1).

38
docs/commands/gen.md Normal file
View file

@ -0,0 +1,38 @@
# Generating a password
## Usage
```
Usage: lprs get <INDEX-or-NAME> [FIELD]
Arguments:
[LENGTH] The password length [default: 18]
Options:
-u, --uppercase With uppercase letters (A-Z)
-l, --lowercase With lowercase letters (a-z)
-n, --numbers With numbers (0-9)
-s, --symbols With symbols (!,# ...)
-h, --help Print help
-V, --version Print version
```
Generate a password with the specified length, by default the length is `18`,
you can specify the length by passing the `LENGTH` argument.
This command is useful when you need to generate a password for a new vault.
## Examples
Generate a password of length 20 with uppercase letters, lowercase letters,
numbers, and symbols:
```sh
lprs gen 20 -ulns
```
Generate a password of length 20 for a new vault:
```sh
lprs add my-vault -u 'username' -p $(lprs gen 20 -ulns)
```
## Notes
- You must specify at least one of the options to generate a password.

57
docs/commands/get.md Normal file
View file

@ -0,0 +1,57 @@
# Getting a vault
## Usage
```
Usage: lprs get <INDEX-or-NAME> [FIELD]
Arguments:
<INDEX-or-NAME>
Whether the index of the vault or its name
[FIELD]
A Specific field to get.
Can be [name, username, password, service, note, totp_secret, totp_code, "string"]
where the string means a custom field
Options:
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
```
Get a single field from a vault, if the field is not provided, the whole vault
will be printed. If the field is a custom field, you need to provide it as a
string.
Also, if the vault you specified does not contained the field you provided, an
error will be returned.
### Examples
Get the whole vault by its index:
```sh
lprs get 1
```
Get the whole vault by its name:
```sh
lprs get my-vault
```
Get a specific field from a vault by its name:
```sh
lprs get my-vault password
```
Get a custom field from a vault by its name:
```sh
lprs get matrix_home_server "host"
```
## Notes
- The index is one-based (the first vault is 1).

111
docs/commands/import-export.md Normal file
View file

@ -0,0 +1,111 @@
# Importing and exporting vaults
## Import usage
```
Usage: lprs import [OPTIONS] <PATH>
Arguments:
<PATH>
The file path to import from
Options:
-f, --format <FORMAT>
The format to import from
[default: lprs]
Possible values:
- lprs: The lprs format, which is the default format and is is the result of the serialization/deserialization of the Vaults struct
- bit-warden: The BitWarden format, which is the result of the serialization/deserialization of the BitWardenPasswords struct
-p, --decryption-password [<DECRYPTION_PASSWORD>]
Decryption password of the imported vaults (in `lprs` format) if there is not, will use the master password
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
```
## Export usage
```
Usage: lprs export [OPTIONS] <PATH>
Arguments:
<PATH>
The path to export to
Options:
-f, --format <FORMAT>
Format to export vaults in
[default: lprs]
Possible values:
- lprs: The lprs format, which is the default format and is is the result of the serialization/deserialization of the Vaults struct
- bit-warden: The BitWarden format, which is the result of the serialization/deserialization of the BitWardenPasswords struct
-p, --encryption-password [<ENCRYPTION_PASSWORD>]
Encryption password of the exported vaults (in `lprs` format) if there is not, will use the master password
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
```
To import and export vaults you need to provide the path to the file to import
from or export to, and you can provide the format to import from or export to,
the format can be `lprs` or `bit-warden`, and the imported or exported file must
be `.json` file.
For the import command, you can provide the decryption password of the imported
vaults if they are exported in the `lprs` format, if there is no decryption
password provided, the master password will be used.
For the export command, you can provide the encryption password of the exported
vaults in the `lprs` format, if there is no encryption password provided, the
master password will be used.
## Examples
Import vaults from a file in the `lprs` format:
```sh
lprs import /path/to/vaults.json
```
Import vaults from a file in the `lprs` format with a decryption password (You
will be prompted for the decryption password):
```sh
lprs import /path/to/vaults.json -p
```
Import vaults from a file in the `bit-warden` format:
```sh
lprs import /path/to/vaults.json -f bit-warden
```
Export vaults to a file in the `lprs` format (is the default format):
```sh
lprs export /path/to/vaults.json
```
export vaults to a file in the `lprs` format with an encryption password (You
will be prompted for the encryption password):
```sh
lprs export /path/to/vaults.json -p
```
Export vaults to a file in the `bit-warden` format:
```sh
lprs export /path/to/vaults.json -f bit-warden
```
## Notes
- The imported or exported file must be a `.json` file.
- The imported vaults will be added to the current vaults.
- The imported vaults must don't have a custom field prefixed with `.lprsfield.`
because it's reserved for backwards compatibility.

24
docs/commands/list.md Normal file
View file

@ -0,0 +1,24 @@
# Listing all vaults
## Usage
```
Usage: lprs list [OPTIONS]
Options:
-f, --filter <TEXT> Filter the select list
-r, --regex Enable regex when use `--filter` option
--json Returns the output as `json` list of vaults
-h, --help Print help
-V, --version Print version
```
Lprs `list` command is used to list all vaults in the vaults file, you can also
filter the list by using the `--filter` option, and you can enable regex by
using the `--regex` flag. Also you can get the output as `json` by using the
`--json` flag (this is useful when you want to use the output in a script and
work with it with `jq`).
### Examples
<script src="https://asciinema.org/a/eEVkDi0NroBjKNILg7KW3hSKY.js" id="asciicast-eEVkDi0NroBjKNILg7KW3hSKY" async="true" data-cols=48 data-rows=10></script>

42
docs/commands/remove.md Normal file
View file

@ -0,0 +1,42 @@
# Removing a vault
## Usage
```
Usage: lprs remove [OPTIONS] <INDEX-or-NAME>
Arguments:
<INDEX-or-NAME> The vault to remove, index or name
Options:
-f, --force Force remove, will not return error if there is no vault with the given index or name
-h, --help Print help
-V, --version Print version
```
To remove a vault you need to provide the index or the name of the vault. If you
provide the index, the vault will be removed by its index, if you provide the
name, the vault will be removed the first vault with the given name.
If there is no vault with the given index or name, an error will be returned,
unless you provide the `--force` option, in which case the command will not
return an error if there is no vault with the given index or name.
## Examples
Remove a vault by its index:
```sh
lprs remove 1
```
Remove a vault by its name:
```sh
lprs remove my-vault
```
Force remove a vault by its index:
```sh
lprs remove 234 --force
```
## Notes
- The index is one-based (the first vault is 1).

13
docs/installation.md Normal file
View file

@ -0,0 +1,13 @@
# Installation
Lprs can be installed using the pre-built binaries or by building from source
via `cargo-install` or `cargo build`, by default the lprs will check for
updates, if you don't want this behavior, you can disable it by passing the
`--no-default-features` flag to the `cargo-install` or `cargo build` command.
And for pre-built binaries, you will find a binary without `lprs-update-notify`,
this binary will not check for updates.
- [Pre-built binaries](https://git.4rs.nl/awiteb/lprs/releases/latest)
- Install using `cargo-install`: `cargo install lprs`
- Building from source, clone the repository and run `cargo build --release` and
copy the binary from the `target/release` directory.

57
docs/introduction.md Normal file
View file

@ -0,0 +1,57 @@
# Lprs Documentation
Welcome to the Lprs documentation. This documentation is intended to help you
get started with the Lprs command line tool `lprs`, and to provide you with a
reference for the various commands and options that are available.
Lprs is a vault manager that allows you to store and retrieve secrets from a
vault. It is designed to be simple to use, and to provide a secure way to manage
your secrets.
Lprs is not for human use only, it is also designed to be used in scripts as
well.
## Encryption
In Lprs, we use the AES-256 CBC encryption algorithm to encrypt and decrypt the
vaults, we ask you for master password, which is used to encrypt and decrypt the
vaults, the master password will be hashed using SHA-256 and the hash will be
used as the key for the AES-256 CBC encryption algorithm. Also we don't store
the master password anywhere, so you have to remember it.
## Storage
The vaults are stored in the program's directory, in a directory called `lprs`
and the file called `vaults.lprs`.
### File location
The file location is dependent on the operating system you are using, here are
the locations for the different operating systems:
| OS | Location |
|--------|-----------------------------------------------|
| Linux | `$HOME/.local/share/lprs/vaults.lprs` |
| MacOS | `$HOME/Library/Application Support/lprs/vaults.lprs` |
| Windows| `{FOLDERID_LocalAppData}\lprs\vaults.lprs` |
### File format
The list of vaults is stored in encrypted binary format.
## Features
- Auto checks for updates (Can be disabled).
- Passing the master password as an argument and via stdin.
- Changing the master password.
- Generating a passwords.
- Store username, password, service name and notes in a vault.
- Custom fields, you can store any key-value pair in a vault.
- TOTP (Time-based One-Time Password) generation. Which can be used to generate
2FA codes.
- Searching for vaults. And list all vaults in json format.
- Importing and exporting encrypted vaults (in json format).
- Importing and exporting from/to Bitwarden json format. (Unencrypted)
- Editing vaults. (The secrets can be passed as arguments or via stdin)
- Deleting vaults.
- Getting single field from a vault. (Useful for scripts)
- Ability to edit, get and remove a vault using its index or name.
- Auto completion for bash, elvish, fish, powershell and zsh
- Ability to import and export vaults with different master passwords. (Useful
for sharing vaults with others)