kvs

README

KVS

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

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

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 Galois Counter Mode (GCM).

• 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 accounts -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 accounts -b google
zRl1TZZe1JVpfAtY1yFU1g==

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

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

👉 You can set the environment variable KVS_SECRET to avoid typing the secret phrase every time.

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=john.doe@gmail.com in a bucket called google and a store called accounts

$ kvs push --store accounts --bucket google user luca.sepe@gmail.com
item successfully stored in bucket 'google' with key 'user'

Example: add a property using shell pipes

$ pwgen | kvs push --store accounts --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 accounts --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 accounts --bucket google hello
item with key 'hello' successfully removed from bucket 'google'

TODO

• encrypt/decrypt secret phrase alternative (using a private key file???)
• implement an env command in order to expose a key-val item as environment variable

Documentation

Overview

Package kvfs provides a simple persistent key-value store.

The API is very simple, you can:

- Put() entries - Get() entries - Delete() entries - Keys() dump all keys in a bucket.

kvfs uses BoltDB for storage.

Index

• Variables
• type KvS
  • func Open(filename string) (*KvS, error)
  • func (rcv *KvS) Buckets() []string
  • func (rcv *KvS) Close() error
  • func (rcv *KvS) Delete(bucket, key string) error
  • func (rcv *KvS) DeleteBucket(bucket string) error
  • func (rcv *KvS) Get(bucket, key string) ([]byte, error)
  • func (rcv *KvS) Keys(bucket string) []string
  • func (rcv *KvS) Put(bucket, key string, value []byte) error

Variables

var (
	// ErrNotFound is returned when the key supplied to a Get or Delete
	// method does not exist in the database.
	ErrNotFound = errors.New("kvs: key not found")

	// ErrBadValue is returned when the value supplied to the Put method
	// is nil.
	ErrBadValue = errors.New("kvs: bad value")

	// ErrBucketNotFound is returned when the bucket name supplied does not exists
	ErrBucketNotFound = errors.New("kvs: bucket not found")
)

Types

type KvS

type KvS struct {
	// contains filtered or unexported fields
}

KvS is the key value store. Use the Open() method to create one, and Close() it when done.

func Open

func Open(filename string) (*KvS, error)

Open a key-value store. "filename" is the full path to the database file, any leading directories must have been created already. File is created with mode 0640 if needed.

"bucket" is a collections of key/value pairs within the database. All keys in a bucket must be unique.

func (*KvS) Buckets

func (rcv *KvS) Buckets() []string

Buckets returns a a list of buckets.

func (*KvS) Close

func (rcv *KvS) Close() error

Close closes the key-value store file.

func (*KvS) Delete

func (rcv *KvS) Delete(bucket, key string) error

Delete the entry with the given key. If no such key is present in the store, it returns ErrNotFound.

func (*KvS) DeleteBucket

func (rcv *KvS) DeleteBucket(bucket string) error

DeleteBucket deletes a bucket. Returns an error if the bucket cannot be found or if the key represents a non-bucket value.

func (*KvS) Get

func (rcv *KvS) Get(bucket, key string) ([]byte, error)

Get an entry from the store. If the key is not present in the store, Get returns ErrNotFound.

func (*KvS) Keys

func (rcv *KvS) Keys(bucket string) []string

Keys returns a list of all the keys in the specified bucket.

func (*KvS) Put

func (rcv *KvS) Put(bucket, key string, value []byte) error

Put an entry into the store. The key can be an empty string, but the value cannot be nil - if it is, Put() returns ErrBadValue.