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/.kvsfolder
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
envcommand 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 (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
Constants ¶
This section is empty.
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") )
Functions ¶
This section is empty.
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 ¶
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) Delete ¶
Delete the entry with the given key. If no such key is present in the store, it returns ErrNotFound.
func (*KvS) DeleteBucket ¶
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 ¶
Get an entry from the store. If the key is not present in the store, Get returns ErrNotFound.
Source Files
Directories