Organize key-value data on your local file system

KVS

Is a commandline tool to store and organize key-value data on your local file system.

  • Built on top of the amazing bbolt db
  • Free open source software
  • Works on Linux, Mac OSX, Windows
  • Just a single portable binary file

KVS

Store

A store is a single file on your local file system.

KVS save all your key-values data grouped by buckets in a specific store.

You can specify the store name using the --store (or the short version -s) flag.

  • each store is located in your $HOME/.kvs folder
  • default store is $HOME/.kvs/vault.db

Buckets

KVS uses buckets to organize your data.

You can specify a bucket using the --bucket (or the short version -b) flag.

  • if you are pushing a key-val pair and the bucket does not exists, it will be created
  • you cannot nest buckets

Keys

Slugs

Performing a push, pull or del command, all keys are transformed into slugs.

  • transliterate Unicode characters into alphanumeric strings

  • all punctuation is stripped and whitespace between words are replaced by hyphens

Example: a key named Hello Wonderful World! became hello-wonderful-world.

Also bucket names are transformed into slugs.

Values

Encryption

KVS can encrypt values using the AES algorithm in CBC mode with PKCS7 padding.

  • the result will be saved as Base64 encoded string

If you want to do so, just add the --encrypt (or the short version -e) flag.

$ kvs push track-id UA-XXXXXXX-X -s demo -b google -e
Secret phrase: 
Secret phrase again:
item successfully stored in bucket 'google' with key 'track-id'

Pulling the value without decription:

$ kvs pull track-id -s demo -b google
zRl1TZZe1JVpfAtY1yFU1g==

to decrypt the value you can use the --decrypt (or the short version -d) flag

$ kvs pull track-id -s demo -b google -d
Secret phrase: 
UA-XXXXXXX-X

Binary values

Values ​​can also be binary data (up to 1MB).

Use cases

  • configuration parameters for others local tools and apps
  • credentials (using the encryption feature)
$ kvs
 _
| | __  __   __    ___ 
| |/ /  \ \ / /  / __|
|   <    \ V /   \__ \
|_|\_\ey  \_/ al |___/ tore

Usage:
  kvs [command]

Available Commands:
  del         Removes from a store the item with the specified key from a bucket
  help        Help about any command
  list        List all bucket names in a store or all key names for a specific bucket
  pull        Fetch from a store the item with the specified key in a bucket
  push        Update a store adding an item with the specified key in a bucket

Flags:
  -h, --help           help for kvs
  -s, --store string   store name (default "vault")
      --version        version for kvs

Use "kvs [command] --help" for more information about a command.

How to store an item

Example: add a property user=luca.sepe@gmail.com in a bucket called google and a store called accounts

$ kvs push --store demo --bucket google user john.doe@gmail.com
item successfully stored in bucket 'google' with key 'user'

Example: add a property using shell pipes (example with pwgen)

$ pwgen | kvs push --store demo --bucket google pass
item successfully stored in bucket 'google' with key 'pass'

How to retrieve an item

Example: retrieve the value of the user property in the bucket google

$ kvs pull --store demo --bucket google user
john.doe@gmail.com

Example: retrieve the encrypted password and pipe to clipboard

$ kvs -b aruba pull pass -d | xclip -selection c
Secret phrase: 

the decrypted password will be saved to your clipboard - ready to be pasted!

How to delete an item

$ kvs del --store demo --bucket google hello
item with key 'hello' successfully removed from bucket 'google'