anydb - a personal key value store
Usage:
anydb <command> [options] [flags]
anydb [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
del Delete key
edit Edit a key
export Export database to json
get Retrieve value for a key
help Help about any command
import Import database dump
info info
list List database contents
man show manual page
serve run REST API listener
set Insert key/value pair
Flags:
-b, --bucket string use other bucket (default: data) (default "data")
-c, --config string toml config file
-f, --dbfile string DB file to use (default "/home/scip/.config/anydb/default.db")
-d, --debug Enable debugging
-h, --help help for anydb
-v, --version Print program version
Use "anydb [command] --help" for more information about a command.Anydb is a commandline personal key value store, it is simple to use and can be used to store anything you'd like, even binary files etc. It uses a key/value store (bbolt) in your home directory.
The tool provides a number of subcommands to use it, there are global options and each subcommand has its own set of options.
-f, --dbfile filename-
The default location of your databas is
$HOME/.config/anydb/default.db. You can change this with the-foption. -b, --bucket name-
Data in a bbolt key-value-store are managed in so called buckets. These are kind of namespaces, where each key must be unique. However, a database may contain more than one bucket.
By default anydb uses a bucket named "data", but you can change this using the option
-b.Buckets can be configured to always encrypt values, see ENCRYTPTION.
-c, --config filename-
Under normal circumstances you don't need a configuration file. But if you want, you can provide one using the option
-c.Anydb looks for a couple of default locations for a config file. You only need this option if you want to supply a configuration on a non-standard location. See CONFIGURATION for more details.
-d, --debug-
Enable debug output.
-h, --help-
Show the usage of anydb.
-v, --version-
Show the program version.
All of these options can be used with subcommands as well.
The completion command can be used to setup completion for anydb. Just put something like this into your shell's configuration file:
source <(anydb completion bash)If you use another shell, specify it instead of bash, of course.
The set command is being used to insert or update a key-value pair.
Usage:
Usage:
anydb set <key> [<value> | -r <file>] [-t <tag>] [flags]
Aliases:
set, add, s, +
Flags:
-e, --encrypt encrypt value
-r, --file string Filename or - for STDIN
-h, --help help for set
-t, --tags tag,tag,... tags, multiple allowedThe standard way to insert a new entry is really simple:
anydb set key valueIf you don't specify a value, anydb expects you to feed it some data via STDIN. For example:
anydb set key < fileYou might as well specify a file directly using the -f option:
anydb set key -f fileValues can be encrypted using ChaCha20Poly1305 when you specify the -e option. Anydb will ask you interactively for a passphrase. You can also provide the passphrase using the environment variable ANYDB_PASSWORD. To encrypt the value, a cryptographically secure key will be derived from the passphrase using the ArgonID2 algorithm. Each value can be encrypted with another passphrase. So, the database itself is not encrypted, just the values.
You can supply tags by using the option -t. Multiple tags can be provided either by separating them with a comma or by using multiple -t parameters:
anydb set key value -t tag1,tag2
anydb set key value -t tag1 -t tag2You can later filter entries by tag or by a combination of tags.
To edit or modify an entry, just use the set command with the same key, the value in the database will be overwritten with the new value. An alternative option is the edit command, see below.
To retrieve the value of a key, use the get subcommand.
Usage:
Usage:
anydb get <key> [-o <file>] [-m <mode>] [-n -N] [-T <tpl>] [flags]
Aliases:
get, show, g, .
Flags:
-h, --help help for get
-m, --mode string output format (simple|wide|json|template) (default 'simple')
-n, --no-headers omit headers in tables
-N, --no-human do not translate to human readable values
-o, --output string output value to file (ignores -m)
-T, --template string go template for '-m template'In its simplest form you just call the get subcommand with the key you want to have the value for. The value is being printed to STDOUT by default:
anydb get keyIf the value is binary content, it will not just being printed. In those cases you need to either redirect output into a file or use the option -o to write to a file:
anydb get key > file
anydb get key -o fileIf the value is encrypted, you will be asked for the passphrase to decrypt it. If the environment variable ANYDB_PASSWORD is set, its value will be used instead.
There are different output modes you can choose from: simple, wide and json. The "simple" mode is the default one, it just prints the value as is. The "wide" mode prints a tabular output similar to the list subcommand, see there for more details. The options -n and -N have the same meaning as in the list command. The "json" mode prints the raw JSON representation of the whole database entry. Decryption will only take place in "simple" and "json" mode. The "template" mode provides the most flexibily, it is detailed in the section TEMPLATES.
The list subcommand displays a list of all database entries.
Usage:
Usage:
anydb list [<filter-regex> | -t <tag> ] [-m <mode>] [-nNif] [-T <tpl>] [flags]
Aliases:
list, ls, /, find, search
Flags:
-i, --case-insensitive filter case insensitive
-h, --help help for list
-m, --mode string output format (table|wide|json|template), wide is a verbose table. (default 'table')
-n, --no-headers omit headers in tables
-N, --no-human do not translate to human readable values
-s, --search-fulltext perform a full text search
-t, --tags stringArray tags, multiple allowed
-T, --template string go template for '-m template'
-l, --wide-output output mode: wideIn its simplest form - without any options - , the list command just prints all keys with their values to STDOUT. Values are being truncated to maximum of 60 characters, that is, multiline values are not completely shown in order to keep the tabular view readable.
To get more informations about each entry, use the -o wide or -l option. In addition to the key and value also the size, update timestamp and tags will be printed. Time and size values are converted into a human readable form, you can suppress this behavior with the -N option. You may omit the headers using the option -n
Sometimes you might want to filter the list of entries. Either because your database grew too large or because you're searching for something. In that case you have two options: You may supply one or more tags or provide a filter regexp. To filter by tag, do:
anydb list -t tag1
anydb list -t tag1,tag2
anydb list -t tag1 -t tag2To filter using a regular expression, do:
anydb list "foo.*bar"Regular expressions follow the golang re2 syntax. For more details about the syntax, refer to https://github.com/google/re2/wiki/Syntax. Please note, that this regexp dialect is not PCRE compatible, but supports most of its features.
If you want to search case insensitive, add the option -i.
By default anydb only searches through the keys. If you want to search through the values as well, then use the -s option, which enables full-text search.
You can - as with the get command - use other output modes. The default mode is "table". The "wide" mode is, as already mentioned, a more detailed table. Also supported is "json" mode and "template" mode. For details about using templates see TEMPLATES.
Use the del command to delete database entries.
Usage:
Usage:
anydb del <key> [flags]
Aliases:
del, d, rm
Flags:
-h, --help help for delThe subcommand del does not provide any further options, it just deletes the entry referred to by the given key. No questions are being asked.
The edit command makes it easier to modify larger entries.
Usage:
Usage:
anydb edit <key> [flags]
Aliases:
edit, modify, mod, ed, vi
Flags:
-h, --help help for editThe subcommand edit does not provide any further options. It works like this:
- 1. Write the value info a temporary file.
- 2. Execute the editor (which one, see below!) with that file.
- 3. Now you can edit the file and save+close it when done.
- 4. Anydb picks up the file and if the content has changed, puts its value into the DB.
By default anydb executes the vi command. You can modify this behavior by setting the environment variable EDITOR appropriately.
Please note, that this does not work with binary content!
Since the bbolt database file is not portable across platforms (it is bound to the endianess of the CPU it was being created on), you might want to create a backup file of your database. You can do this with the export subcommand.
Usage:
Usage:
anydb export -o <json filename> [flags]
Aliases:
export, dump, backup
Flags:
-h, --help help for export
-o, --output string output to fileThe database dump is a JSON representation of the whole database and will be printed to the file specified with the -o option. If you specify "-" as the filename, it will be written to STDIN.
anydb export -o dump.json
anydb export -o - > dump.jsonPlease note, that encrypted values will not be decrypted. This might change in a future version of anydb.
The import subcommand can be used to restore a database from a JSON dump.
Usage:
Usage:
anydb import -i <json file> [flags]
Aliases:
import, restore
Flags:
-r, --file string Filename or - for STDIN
-h, --help help for import
-t, --tags stringArray tags, multiple allowedThe import subcommand reads the JSON contents from the file specified with the -i option. If you specify "-" as the filename, it will be read from STDIN.
anydb import -i - < dump.json
anydb import -i dump.json
cat dump.json | anydb import -i -If there is already a database, it will be saved by appending a timestamp and a new database with the contents of the dump will be created.
Anydb provides a RESTful API, which you can use to manage the database from somewhere else. The API does not provide any authentication or any other security measures, so better only use it on localhost.
Usage:
Usage:
anydb serve [-l host:port] [flags]
Flags:
-h, --help help for serve
-l, --listen string host:port (default "localhost:8787")To start the listener, just execute the serve subcommand. You can tweak the ip address and tcp port using the -l option. The listener will not fork and run in the foreground. Logs are being printed to STDOUT as long as the listener runs.
For more details about the API, please see the "REST API" section.
The info subcommand shows you some information about your current database.
Usage:
Usage:
anydb info [flags]
Flags:
-h, --help help for info
-N, --no-human do not translate to human readable valuesData being shown are: filename and size, number of keys per bucket. If you supply the -d option (debug), some bbolt internals are being displayed as well.
The man subcommand shows an unformatted text variant of the manual page (which are currently reading).
Usage:
Usage:
anydb man [flags]
Flags:
-h, --help help for manThe manual is being piped into the more command, which is being expected to exist according to the POSIX standard on all supported unix platforms. It might not work on Windows.
The get and list commands support a template feature, which is very handy to create you own kind of formatting. The template syntax being used is the GO template language, refer to https://pkg.go.dev/text/template for details.
Each template operates on one or more entries, no loop construct is required, the template provided applies to every matching entry separatley.
The following template variables can be used:
- Key - string
- Value - string
- Bin - []byte
- Created - time.Time
- Encrypted bool
Prepend a single dot (".") before each variable name.
Here are some examples how to use the feature:
Only show the keys of all entries:
anydb list -m template -T "{{ .Key }}"Format the list in a way so that is possible to evaluate it in a shell:
eval $(anydb get foo -m template -T "key='{{ .Key }}' value='{{ .Value }}' ts='{{ .Created}}'")
echo "Key: $key, Value: $value"Print the values in CSV format ONLY if they have some tag:
anydb list -m template -T "{{ if .Tags }}{{ .Key }},{{ .Value }},{{ .Created}}{{ end }}"Anydb looks at the following locations for a configuration file, in that order:
$HOME/.config/anydb/anydb.toml$HOME/.anydb.tomlanydb.tomlin the current directory- or specify one using
-c
The configuration format uses the TOML language, refer to https://toml.io/en/ for more details. The key names correspond to the commandline options in most cases.
Configuration follows a certain precedence: the files are tried to be read in the given order, followed by commandline options. That is, the last configuration file wins, unless the user provides a commandline option, then this setting will be taken.
A complete configuration file might look like this:
# defaults
dbfile = "~/.config/anydb/default.db"
dbbucket = "data"
noheaders = false
nohumanize = false
encrypt = false
listen = "localhost:8787"
# different setups for different buckets
[buckets.data]
encrypt = true
[buckets.test]
encrypt = falseUnder normal circumstances you don't need a configuration file. However, if you want to use different buckets, then this might be a handy option. Buckets are being configured in ini-style with the term "bucket." followed by the bucket name. In the example above we enable encryption for the default bucket "data" and disable it for a bucket "test". To use different buckets, use the -b option.
The subcommand serve starts a simple HTTP service, which responds to RESTful HTTP requests. The listener responds to all requests with a JSON encoded response. The response contains the status and the content - if any - of the requested resource.
The following requests are supported:
- GET /anydb/v1/
-
Returns a JSON encoded list of all entries.
- GET /anydb/v1/key
-
Returns the JSON encoded entry, if found.
- PUT /anydb/v1/
-
Create an entry. Expects a JSON encoded request object in POST data.
- DELETE /anydb/v1/key
-
Delete an entry.
Some curl example calls to the API:
Post a new key: curl -X PUT localhost:8787/anydb/v1/ \ -H 'Content-Type: application/json' \ -d '{"key":"foo","val":"bar"}'
Retrieve the value:
curl localhost:8787/anydb/v1/fooList all keys:
curl localhost:8787/anydb/v1/In order to report a bug, unexpected behavior, feature requests or to submit a patch, please open an issue on github: https://github.com/TLINDEN/anydb/issues.
Please repeat the failing command with debugging enabled -d and include the output in the issue.
The REST API list request doesn't provide any filtering capabilities yet.
This software is licensed under the GNU GENERAL PUBLIC LICENSE version 3.
Copyright (c) 2024 by Thomas von Dein
Thomas von Dein tom AT vondein DOT org