feat: Lprs docs (#49)
Reviewed-on: #49 Co-authored-by: Awiteb <a@4rs.nl> Co-committed-by: Awiteb <a@4rs.nl>
This commit is contained in:
parent
0a238dc336
commit
f9d36a2dd7
17 changed files with 723 additions and 64 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
@ -1 +1,2 @@
|
||||||
/target
|
/target
|
||||||
|
/book
|
||||||
|
|
105
README.md
105
README.md
|
@ -1,94 +1,89 @@
|
||||||
|
|
||||||
|
<div align="center">
|
||||||
|
|
||||||
# Lprs
|
# Lprs
|
||||||
|
A local vault manager designed to securely store and manage your vaults.
|
||||||
|
|
||||||
Lprs is a local vault manager designed to securely store and manage your vaults.
|
[![Docs](https://img.shields.io/badge/docs-lprs.4rs.nl-purple)](https://lprs.4rs.nl)
|
||||||
|
[![Crates.io](https://img.shields.io/crates/v/lprs?color=orange)](https://crates.io/crates/lprs)
|
||||||
|
[![Forgejo CI Status](https://git.4rs.nl/awiteb/lprs/badges/workflows/ci.yml/badge.svg)](https://git.4rs.nl/awiteb/lprs)
|
||||||
|
[![Forgejo CD Status](https://git.4rs.nl/awiteb/lprs/badges/workflows/cd.yml/badge.svg)](https://git.4rs.nl/awiteb/lprs)
|
||||||
|
|
||||||
### MSRV
|
</div>
|
||||||
The Minimum Supported Rust Version (MSRV) is `1.70.0`.
|
|
||||||
|
## 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)
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
To install Lprs, you will need to have the Cargo package manager installed. If you do not have Cargo installed, you can install it by following the instructions [here](https://doc.rust-lang.org/cargo/getting-started/installation.html).
|
### Build from source (MSRV: `1.74.0`)
|
||||||
|
|
||||||
|
|
||||||
1. Install using [cargo-install](https://doc.rust-lang.org/cargo/commands/cargo-install.html):
|
|
||||||
```bash
|
```bash
|
||||||
cargo install lprs --locked
|
# From crates.io
|
||||||
```
|
cargo install lprs
|
||||||
This will enable the update notifications for Lprs. If you don't want to enable update notifications, you can install Lprs using:
|
# From source (after cloning the repository)
|
||||||
```bash
|
# The binary will be in target/release/lprs
|
||||||
cargo install lprs --locked --no-default-features
|
cargo build --release
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Run Lprs:
|
This will build Lprs with update checking enabled. If you want to disable update checking, you can build Lprs without the default features by passing the `--no-default-features` flag.
|
||||||
```bash
|
|
||||||
lprs --help
|
|
||||||
```
|
|
||||||
|
|
||||||
## Uninstallation
|
### Pre-built binaries
|
||||||
```bash
|
Pre-built binaries are available for Linux only, you can download them from the [releases page](https://git.4rs.nl/awiteb/lprs/releases/latest).
|
||||||
cargo uninstall lprs
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Lprs provides a command-line interface for managing your vaults. The following commands are available:
|
Lprs provides a command-line interface for managing your vaults. The following commands are available:
|
||||||
|
|
||||||
```
|
```
|
||||||
A local CLI password manager
|
A local CLI vaults manager. For human and machine use
|
||||||
|
|
||||||
Usage: lprs [OPTIONS] <COMMAND>
|
Usage: lprs [OPTIONS] <COMMAND>
|
||||||
|
|
||||||
Commands:
|
Commands:
|
||||||
add Add new vault
|
add Add new vault
|
||||||
remove Remove vault
|
remove Remove vault [alias `rm`]
|
||||||
list List your vaults and search
|
list List your vaults and search [alias `ls`]
|
||||||
clean Clean the vaults file
|
clean Clean the vaults file
|
||||||
edit Edit the vault content
|
edit Edit the vault content
|
||||||
gen Generate a password
|
gen Generate a password
|
||||||
|
get Get a entire vault or single field from it
|
||||||
export Export the vaults
|
export Export the vaults
|
||||||
import Import vaults
|
import Import vaults
|
||||||
|
change-master-password Change the master password
|
||||||
|
completion Generate shell completion
|
||||||
help Print this message or the help of the given subcommand(s)
|
help Print this message or the help of the given subcommand(s)
|
||||||
|
|
||||||
Options:
|
Options:
|
||||||
-v, --vaults-file <VAULTS_FILE> The vaults json file
|
-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
|
-h, --help Print help
|
||||||
-V, --version Print version
|
-V, --version Print version
|
||||||
```
|
```
|
||||||
|
|
||||||
### Example
|
## Documentation
|
||||||
```bash
|
You can find the full documentation for Lprs on the official website at https://lprs.4rs.nl.
|
||||||
lprs add -n "Gmail" -u "some@gmail.com" -p $(lprs gen 19 -u -l -s) -s "https://mail.google.com"
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Result
|
|
||||||
This is the result when search for it
|
|
||||||
```
|
|
||||||
$ lprs list -e "mail" -p -s
|
|
||||||
Master Password: ***************
|
|
||||||
+-------+-------+----------------+---------------------+-------------------------+
|
|
||||||
| Index | Name | Username | Password | Service |
|
|
||||||
+================================================================================+
|
|
||||||
| 31 | Gmail | some@gmail.com | >NC`q$%+Nno<y&<y]VB | https://mail.google.com |
|
|
||||||
+-------+-------+----------------+---------------------+-------------------------+
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
### Backup
|
|
||||||
|
|
||||||
It is important to regularly backup your vaults to prevent data loss. Lprs does not provide an automatic backup feature. To backup your vaults, you can use the `export` command provided by Lprs. This command allows you to export your encrypted vaults to a json file, which you can then manually backup to a secure location.
|
|
||||||
|
|
||||||
#### Formats
|
|
||||||
The format of the exported file can be specified using the `--format` option. The following formats are supported:
|
|
||||||
|
|
||||||
- `lprs`: The default format used by Lprs. This format is encrypted and can be imported back into Lprs using the `import` command. This is the recommended format to use for backups as it is encrypted and can be imported back into Lprs.
|
|
||||||
- `bit-warden`: The format used by [Bitwarden](https://bitwarden.com/). This format is not encrypted and can be imported into Bitwarden. This format is useful if you want to switch to Bitwarden or another password manager that supports this format.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
Contributions to Lprs are welcome! If you would like to contribute, please follow the guidelines outlined in the [CONTRIBUTING]
|
Contributions to Lprs are welcome! If you would like to contribute, please follow the guidelines outlined in the [CONTRIBUTING.md](CONTRIBUTING.md) file.
|
||||||
(CONTRIBUTING.md) file.
|
|
||||||
|
|
||||||
## Mirrors
|
## Mirrors
|
||||||
This repository is mirrored on the following platforms:
|
This repository is mirrored on the following platforms:
|
||||||
|
|
6
book.toml
Normal file
6
book.toml
Normal file
|
@ -0,0 +1,6 @@
|
||||||
|
[book]
|
||||||
|
authors = ["Awiteb"]
|
||||||
|
language = "en"
|
||||||
|
multilingual = false
|
||||||
|
src = "docs"
|
||||||
|
title = "Lprs Documentation"
|
15
docs/SUMMARY.md
Normal file
15
docs/SUMMARY.md
Normal 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
46
docs/commands/README.md
Normal 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
92
docs/commands/add.md
Normal 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
25
docs/commands/auto-completion.md
Normal 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` |
|
32
docs/commands/change-master-password.md
Normal file
32
docs/commands/change-master-password.md
Normal file
|
@ -0,0 +1,32 @@
|
||||||
|
# Changing the master password
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```
|
||||||
|
Usage: lprs change-master-password [NEW_PASSWORD]
|
||||||
|
|
||||||
|
Arguments:
|
||||||
|
[NEW_PASSWORD] The new master password, if there is no value for it you will prompt it
|
||||||
|
|
||||||
|
Options:
|
||||||
|
-h, --help Print help
|
||||||
|
```
|
||||||
|
|
||||||
|
A command to change the master password of the vaults file, you can provide the
|
||||||
|
new password as an argument or you will be prompted for it.
|
||||||
|
|
||||||
|
### Example
|
||||||
|
Prompt for the new master password
|
||||||
|
```bash
|
||||||
|
lprs change-master-password
|
||||||
|
```
|
||||||
|
|
||||||
|
Change the master password to `new-password`
|
||||||
|
```bash
|
||||||
|
lprs change-master-password 'new-password'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Note
|
||||||
|
- The master password is used to encrypt and decrypt the vaults file, so if you
|
||||||
|
forget it you will lose all your vaults.
|
||||||
|
- This action is irreversible, so make sure to remember the new password.
|
19
docs/commands/clean.md
Normal file
19
docs/commands/clean.md
Normal 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
85
docs/commands/edit.md
Normal 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
38
docs/commands/gen.md
Normal 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
57
docs/commands/get.md
Normal 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
111
docs/commands/import-export.md
Normal 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
24
docs/commands/list.md
Normal 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
42
docs/commands/remove.md
Normal 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
13
docs/installation.md
Normal 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.
|
58
docs/introduction.md
Normal file
58
docs/introduction.md
Normal file
|
@ -0,0 +1,58 @@
|
||||||
|
# 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 (even the hash of it), so if you forget it you will
|
||||||
|
lose all your vaults.
|
||||||
|
|
||||||
|
## 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)
|
Loading…
Reference in a new issue