local-kv-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# local-kv-cli
+
+A tiny, zero-dependency CLI to store key-value pairs locally on your machine.
+
+## Install
+
+```bash
+npm install -g local-kv-cli
+```
+
+## Usage
+
+```bash
+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 list                              # show all pairs (add --json for JSON)
+lkv delete api_url                    # remove a pair
+lkv clear                             # remove everything
+lkv path                              # show where data is stored
+```
+
+`set` won't overwrite an existing key; use `update`, or `set <key> <value> --force`.
+
+Data is stored in `~/.local-kv/store.json`. Set `LKV_STORE_PATH` to use a different file.
+
+## Use from code
+
+```ts
+import { Store } from "local-kv-cli";
+
+const store = new Store();
+store.set("visits", "1");
+store.get("visits"); // "1"
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { Store } from "./store";
+export declare function run(argv: string[], store?: Store): void;

package/dist/cli.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const store_1 = require("./store");
+const HELP = `lkv - store key-value pairs locally
+
+Usage:
+  lkv set <key> <value> [--force]   Create a pair (--force overwrites)
+  lkv get <key>                     Print the value of a key
+  lkv update <key> <value>          Change the value of an existing key
+  lkv delete <key>                  Remove a pair
+  lkv list [--json]                 Show all pairs
+  lkv clear                         Remove all pairs
+  lkv path                          Show where the data file lives
+  lkv help                          Show this help
+
+Tip: quote values with spaces, e.g.  lkv set greeting "hello world"`;
+function fail(message) {
+    console.error(`Error: ${message}`);
+    process.exit(1);
+}
+function requireArgs(args, count, usage) {
+    if (args.length < count)
+        fail(`Usage: lkv ${usage}`);
+}
+function run(argv, store = new store_1.Store()) {
+    const flags = new Set(argv.filter((a) => a.startsWith("--")));
+    const [command, ...args] = argv.filter((a) => !a.startsWith("--"));
+    switch (command) {
+        case "set": {
+            requireArgs(args, 2, "set <key> <value>");
+            const [key, ...rest] = args;
+            store.set(key, rest.join(" "), flags.has("--force"));
+            console.log(`Saved "${key}"`);
+            break;
+        }
+        case "get": {
+            requireArgs(args, 1, "get <key>");
+            const value = store.get(args[0]);
+            if (value === undefined)
+                fail(`Key "${args[0]}" not found`);
+            console.log(value);
+            break;
+        }
+        case "update": {
+            requireArgs(args, 2, "update <key> <value>");
+            const [key, ...rest] = args;
+            store.update(key, rest.join(" "));
+            console.log(`Updated "${key}"`);
+            break;
+        }
+        case "delete":
+        case "rm": {
+            requireArgs(args, 1, "delete <key>");
+            if (!store.delete(args[0]))
+                fail(`Key "${args[0]}" not found`);
+            console.log(`Deleted "${args[0]}"`);
+            break;
+        }
+        case "list":
+        case "ls": {
+            const data = store.all();
+            if (flags.has("--json")) {
+                console.log(JSON.stringify(data, null, 2));
+                break;
+            }
+            const keys = Object.keys(data);
+            if (keys.length === 0) {
+                console.log("(empty)");
+                break;
+            }
+            const width = Math.max(...keys.map((k) => k.length));
+            for (const key of keys)
+                console.log(`${key.padEnd(width)}  ${data[key]}`);
+            break;
+        }
+        case "clear":
+            store.clear();
+            console.log("All pairs removed");
+            break;
+        case "path":
+            console.log(store.path);
+            break;
+        case undefined:
+        case "help":
+            console.log(HELP);
+            break;
+        default:
+            fail(`Unknown command "${command}". Run "lkv help".`);
+    }
+}
+if (require.main === module) {
+    try {
+        run(process.argv.slice(2));
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Store, getStorePath } from "./store";
+export type { Data } from "./store";

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStorePath = exports.Store = void 0;
+// Public API, so the store can also be used from code: import { Store } from "local-kv-cli"
+var store_1 = require("./store");
+Object.defineProperty(exports, "Store", { enumerable: true, get: function () { return store_1.Store; } });
+Object.defineProperty(exports, "getStorePath", { enumerable: true, get: function () { return store_1.getStorePath; } });

package/dist/store.d.ts

@@ -0,0 +1,20 @@
+export type Data = Record<string, string>;
+/** Where the data lives. Override with the LKV_STORE_PATH env variable. */
+export declare function getStorePath(): string;
+export declare class Store {
+    private readonly filePath;
+    constructor(filePath?: string);
+    get path(): string;
+    private read;
+    private write;
+    has(key: string): boolean;
+    /** Create a new pair. Throws if the key already exists (use update, or force). */
+    set(key: string, value: string, force?: boolean): void;
+    get(key: string): string | undefined;
+    /** Change an existing pair. Throws if the key does not exist. */
+    update(key: string, value: string): void;
+    /** Returns true if the key existed and was removed. */
+    delete(key: string): boolean;
+    all(): Data;
+    clear(): void;
+}

package/dist/store.js

@@ -0,0 +1,116 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Store = void 0;
+exports.getStorePath = getStorePath;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/** Where the data lives. Override with the LKV_STORE_PATH env variable. */
+function getStorePath() {
+    return process.env.LKV_STORE_PATH || path.join(os.homedir(), ".local-kv", "store.json");
+}
+class Store {
+    filePath;
+    constructor(filePath = getStorePath()) {
+        this.filePath = filePath;
+    }
+    get path() {
+        return this.filePath;
+    }
+    read() {
+        // Prototype-less object so keys like "constructor" or "__proto__" are just normal keys.
+        const data = Object.create(null);
+        if (!fs.existsSync(this.filePath))
+            return data;
+        const raw = fs.readFileSync(this.filePath, "utf8");
+        if (!raw.trim())
+            return data;
+        try {
+            return Object.assign(data, JSON.parse(raw));
+        }
+        catch {
+            throw new Error(`Store file is corrupted: ${this.filePath}`);
+        }
+    }
+    write(data) {
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        // Write to a temp file then rename, so a crash never leaves a half-written store.
+        const tmp = `${this.filePath}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+        fs.renameSync(tmp, this.filePath);
+    }
+    has(key) {
+        return key in this.read();
+    }
+    /** Create a new pair. Throws if the key already exists (use update, or force). */
+    set(key, value, force = false) {
+        const data = this.read();
+        if (!force && key in data) {
+            throw new Error(`Key "${key}" already exists. Use "update" to change it.`);
+        }
+        data[key] = value;
+        this.write(data);
+    }
+    get(key) {
+        const data = this.read();
+        return key in data ? data[key] : undefined;
+    }
+    /** Change an existing pair. Throws if the key does not exist. */
+    update(key, value) {
+        const data = this.read();
+        if (!(key in data)) {
+            throw new Error(`Key "${key}" not found. Use "set" to create it.`);
+        }
+        data[key] = value;
+        this.write(data);
+    }
+    /** Returns true if the key existed and was removed. */
+    delete(key) {
+        const data = this.read();
+        if (!(key in data))
+            return false;
+        delete data[key];
+        this.write(data);
+        return true;
+    }
+    all() {
+        return this.read();
+    }
+    clear() {
+        this.write({});
+    }
+}
+exports.Store = Store;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "local-kv-cli",
+  "version": "1.0.0",
+  "description": "A tiny CLI to store key-value pairs locally on your machine",
+  "keywords": [
+    "cli",
+    "key-value",
+    "kv",
+    "store",
+    "local",
+    "storage"
+  ],
+  "license": "MIT",
+  "author": "",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "lkv": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2"
+  }
+}