local-kv-cli

A tiny, zero-dependency CLI to store key-value pairs locally on your machine, with typed values, counters, history, namespaces, per-project stores and environment variable export.

Install

npm install -g local-kv-cli

Basics

lkv set api_url https://example.com   # create a pair
lkv get api_url                       # print a value
lkv update api_url https://new.com    # change an existing value
lkv rename api_url base_url           # rename a key
lkv delete base_url                   # remove a pair
lkv list                              # show all pairs
lkv clear                             # remove everything in the namespace

set won't overwrite an existing key; use update, or set <key> <value> --force.

Typed values

Numbers, true/false and JSON are stored with their type:

lkv set retries 3                 # number
lkv set debug true                # boolean
lkv set config '{"port":8080}'    # JSON
lkv set zip 02134                 # stays text (leading zero)
lkv set -t string code 42         # force a type: string, number, boolean or json
lkv get config --json             # print as JSON

Counters

lkv incr build_count      # 1  (missing keys start at 0)
lkv incr build_count 10   # 11
lkv decr build_count      # 10

History and details

Every change keeps the previous value (the last 20 per key).

lkv history retries   # current value first, then older ones
lkv list --long       # type and last update time for each key

Search

lkv search example            # key or value contains "example"
lkv list --filter api         # key contains "api"
lkv list --json               # everything as JSON

Namespaces

Keep separate groups of values:

lkv -n work set token abc123
lkv -n work list
lkv namespaces               # list namespaces and how many keys each has

You can also set the LKV_NAMESPACE environment variable.

Per-project stores

cd my-project
lkv init        # creates .lkv.json here
lkv set port 3000

Inside that folder (and its subfolders) lkv uses the project's .lkv.json. Add --global (-g) to use your global store instead. Add .lkv.json to .gitignore if it holds private values.

lkv path shows which file is in use.

Environment variables

eval "$(lkv env)"                    # bash / zsh
lkv env | Invoke-Expression          # PowerShell
lkv env --shell cmd                  # cmd.exe syntax
lkv env --upper                      # API_URL instead of api_url

lkv run npm start                    # run a command with your values as env variables

Keys that aren't valid variable names (like my-key) are skipped with a warning.

Backup and restore

lkv export backup.json          # current namespace
lkv export backup.json --all    # every namespace
lkv import backup.json          # skips keys that already exist
lkv import backup.json --force  # overwrite them

import also accepts a plain { "key": "value" } JSON object.

Clipboard

lkv get api_url --copy

On Linux this needs wl-clipboard, xclip or xsel.

Where data is stored

1. The file in the LKV_STORE_PATH environment variable, if set
2. Otherwise a .lkv.json in the current folder or a parent folder
3. Otherwise ~/.local-kv/store.json

Use from code

import { Store } from "local-kv-cli";

const store = new Store();                        // same lookup as the CLI
const work = new Store({ namespace: "work" });
const custom = new Store({ path: "./data.json" });

store.set("visits", 0);
store.incr("visits");            // 1
store.get("visits");             // 1
store.history("visits");         // [{ value: 0, type: "number", updated: "..." }]
store.entry("visits");           // value, type, created, updated, history

Upgrading from 1.x

Your data is upgraded automatically the first time 2.x runs, and a copy of the old file is saved next to it as store.json.v1-backup. See CHANGELOG.md for breaking changes.

License

MIT