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)

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
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.

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.

Donations

You can support the development of my projects by donating me, check out my profile at git.4rs.nl

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
          
          If there is no value, you will enter it through a prompt

  -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')

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:

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:

# -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:

# 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.

Removing a vault

Usage

Usage: lprs remove [OPTIONS] [INDEX-or-NAME]...

Arguments:
  [INDEX-or-NAME]...  The vaults 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

To remove a vaults you need to provide the index or the name of each 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 vaults by its index:

lprs remove 1 10 14

Remove a vault by its name:

lprs remove my-vault 'another vault' "third vault"

Force remove a vault by its index (will not return an error if there is no vault with the given index):

lprs remove 234 --force

Notes

The index is one-based (the first vault is 1).

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, make it empty string to delete it

  -p, --password [<PASSWORD>]
          The new password, make it empty string to delete it
          
          If there is no value for it you will prompt it

  -s, --service <SERVICE>
          The new vault service, make it empty string to delete it

  -o, --note <NOTE>
          The new vault note

  -t, --totp-secret [<TOTP_SECRET>]
          The TOTP secret, make it empty string to delete it
          
          If there is no value you will prompt it

  -c, --custom <KEY=VALUE>
          The custom field, make it empty string to delete it
          
          If the custom field not exist will created it, if it's will update it, if there is no value, you will enter it through a prompt (e.g `-c key`)

  -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')

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.

Field removal

If you want to remove a field from the vault, you can provide an empty value for it, e.g. -o "".

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:

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:

# You will be prompted for the new password
lprs edit my-vault -p

Remove a custom field from a vault by its name:

lprs edit my-vault -c key1=""

Notes

The index is one-based (the first vault is 1).

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')

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:

lprs get 1

Get the whole vault by its name:

lprs get my-vault

Get a specific field from a vault by its name:

lprs get my-vault password

Get a custom field from a vault by its name:

lprs get matrix_home_server "host"

Notes

The index is one-based (the first vault is 1).

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

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

Clening the vaults

Usage

Usage: lprs clean

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.

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

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:

lprs gen 20 -ulns

Generate a password of length 20 for a new vault:

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.

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')

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:

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):

lprs import /path/to/vaults.json -p

Import vaults from a file in the bit-warden format:

lprs import /path/to/vaults.json -f bit-warden

Export vaults to a file in the lprs format (is the default format):

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):

lprs export /path/to/vaults.json -p

Export vaults to a file in the bit-warden format:

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.

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

lprs change-master-password

Change the master password to new-password

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.

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`