foks kv

Overview

The FOKS key-value store lets you store secrets, configuration, and files with end-to-end encryption. The namespace uses a filesystem-like hierarchy with paths like /secrets/api-key or /configs/db.json. Data is encrypted on your machine before being sent to the server. The server never sees file names or contents.

Common flags

Most kv subcommands accept these flags:

Flag	Description
`--team <team>` / `-t <team>`	Act on behalf of a team. Defaults to operating as the logged-in user.
`--mkdir-p` / `-p`	Create parent directories automatically
`--read-role <role>` / `-r`	Minimum role required to read (owner, admin, member, member(n), reader)
`--write-role <role>` / `-w`	Minimum role required to write

Commands

put

foks kv put <key> [<value>] [flags]

Store a value at the given path.

# Store a string
foks kv put /secrets/api-key "mysecret"

# Read value from stdin
echo "mysecret" | foks kv put /secrets/api-key

# Store a file
foks kv put /configs/settings.json --file settings.json

# Store for a team
foks kv put --team myteam /shared/db-password "secret"

# Overwrite an existing entry
foks kv put /secrets/api-key "newvalue" --force

# Create parent directories automatically
foks kv put /a/b/c/key "value" --mkdir-p

Flags:

Flag	Description
`--file` / `-f`	Treat the value argument as a filename to read from (use `-` for stdin)
`--force`	Overwrite an existing entry
`--read-role` / `-r`	Read role for the entry
`--write-role` / `-w`	Write role for the entry
`--mkdir-p` / `-p`	Create parent directories

get

foks kv get <key> [<output-file>] [flags]

Retrieve a value. If no output file is given (or - is given), prints to stdout. If stdout is a terminal and the data appears to be binary, an error is returned.

# Print to stdout
foks kv get /secrets/api-key

# Write to a file
foks kv get /configs/settings.json settings.json

# Force output to terminal even if binary
foks kv get /data/binary-blob --force-output

Flags:

Flag	Description
`--force`	Overwrite existing output file
`--force-output`	Output to terminal even if data looks binary
`--mode <octal>`	File permissions for the output file (e.g. `0600`)

ls

foks kv ls <path> [flags]
foks kv list <path> [flags]

List the contents of a directory in the key-value store.

foks kv ls /secrets
foks kv ls /secrets -l          # long format with type and timestamp
foks kv ls /secrets -F          # append '/' to directory names
foks kv ls /secrets -l -U       # timestamps as Unix milliseconds

Flags:

Flag	Description
`-F` / `--classify`	Append `/` to directory names
`-l` / `--long`	Long format with entry type and modification time
`-U` / `--unix-time`	Print timestamps as Unix milliseconds

mkdir

foks kv mkdir <path> [flags]

Create a directory.

foks kv mkdir /secrets
foks kv mkdir /a/b/c --mkdir-p    # create all parents

rm

foks kv rm <key> [<key2> ...] [flags]
foks kv remove <key> ...
foks kv unlink <key> ...
foks kv delete <key> ...

Remove one or more entries.

foks kv rm /secrets/old-key
foks kv rm /a/b/c -r              # remove a directory recursively

Flags:

Flag	Description
`-r` / `--recursive`	Remove a directory and all its contents

mv

foks kv mv <src> <dst>
foks kv move <src> <dst>
foks kv rename <src> <dst>

Move or rename an entry.

foks kv mv /secrets/old-name /secrets/new-name
foks kv mv /secrets /archive/secrets    # move a whole directory

symlink

foks kv symlink <path> <target>
foks kv ln <path> <target>

Create a symbolic link within the key-value store.

foks kv symlink /current/config /configs/v2/config

readlink

foks kv readlink <path>

Print the target of a symbolic link.

get-usage

foks kv get-usage
foks kv du

Show storage usage for the current user (or team with --team).

rest

foks kv rest start [flags]
foks kv rest stop

Start a local loopback REST API server for the key-value store. Useful for integrating FOKS with scripts or tools that speak HTTP.

Roles

Entries and directories have read and write roles. The role hierarchy is:

owner > admin > member(n) > reader

The member role carries a signed integer sub-level n in the range -16384 to 16384 (default 0). Sub-levels are linearizable, so member(1) is higher privilege than member(0), which is higher than member(-1). Plain member is shorthand for member(0). When you create an entry with --read-role member, only team members with the member(0) role or higher can decrypt it. To restrict to a higher sub-level, use e.g. --read-role member(1). Write permissions are enforced by the server; read permissions are enforced cryptographically.

Paths

Paths are Unix-style hierarchical paths starting with /. Example:

/secrets/database/production/password
/configs/nginx.conf
/shared/certificates/tls.pem

Getting Started

Core Concepts

CLI Reference

Self-Hosting

Overview

Common flags

Commands

put

get

ls

mkdir

rm

mv

symlink

readlink

get-usage

rest

Roles

Paths

​Overview

​Common flags

​Commands

​put

​get

​ls

​mkdir

​rm

​mv

​symlink

​readlink

​get-usage

​rest

​Roles

​Paths

Overview

Common flags

Commands

put

get

ls

mkdir

rm

mv

symlink

readlink

get-usage

rest

Roles

Paths