From b74564fd9bafc353276a8f797146c28e829320f1 Mon Sep 17 00:00:00 2001
From: Fredrik Johansson <fredrik.johansson@intraphone.com>
Date: Wed, 15 Jul 2026 15:38:12 +0200
Subject: [PATCH] Add a real global keep CLI instead of npm run cli --

npm run cli -- <args> only works from inside this repo's directory,
which is awkward everywhere but especially on a deploy host running
this alongside a dozen other projects. scripts/install-cli.sh builds
the CLI and symlinks dist/cli/index.js onto PATH (~/.local/bin by
default, no root/global npm install needed) as a real `keep` command,
runnable from anywhere.

Symlinked rather than copied, so a future `git pull && npm run build`
is the entire upgrade story -- no need to re-run the install script
after the first time.

Verified: keep --help and keep identity show both work correctly from
unrelated directories (/tmp, $HOME) after running the install script,
confirming no hidden cwd dependency.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .env.example           |  3 +++
 README.md              | 27 +++++++++++++++++----------
 scripts/install-cli.sh | 23 +++++++++++++++++++++++
 3 files changed, 43 insertions(+), 10 deletions(-)
 create mode 100755 scripts/install-cli.sh

diff --git a/.env.example b/.env.example
index 8de1317..ce61566 100644
--- a/.env.example
+++ b/.env.example
@@ -1,6 +1,9 @@
 PORT=3050
 DATA_DIR=./data
 
+# Image to run via docker compose, e.g. repo.example.com/owner/keep:latest
+IMAGE=
+
 # Gates recipient add/remove and revoke. Unset disables /api/admin/* (503)
 # but push/pull/grant keep working for already-registered recipients.
 ADMIN_PASSWORD=change-me
diff --git a/README.md b/README.md
index 767c5f7..b6fec48 100644
--- a/README.md
+++ b/README.md
@@ -91,22 +91,29 @@ cp .env.example .env
 npm install
 npm run dev:server
 
-# 2. Each machine/person that needs access generates its own identity
-npm run cli -- identity init
+# 2. Build the CLI and link it onto PATH as a real `keep` command --
+#    no npm run cli --, no cd-ing into this repo from wherever you
+#    actually need it (a deploy directory on some VPS, for instance).
+#    Symlinked, not copied: a future `git pull && npm run build` here
+#    is the entire upgrade story, no need to re-run this.
+./scripts/install-cli.sh
+
+# 3. Each machine/person that needs access generates its own identity
+keep identity init
 #   → prints a public key
 
-# 3. An admin registers that public key as a recipient
-KEEP_ADMIN_PASSWORD=... npm run cli -- recipient add --label "my-laptop" --pubkey <hex>
+# 4. An admin registers that public key as a recipient
+KEEP_ADMIN_PASSWORD=... keep recipient add --label "my-laptop" --pubkey <hex>
 #   → prints a recipient id
 
-# 4. The machine that generated the identity records its assigned id
-npm run cli -- identity set-id <recipient-id>
+# 5. The machine that generated the identity records its assigned id
+keep identity set-id <recipient-id>
 
-# 5. Push a vault — the pusher is automatically its first recipient
-npm run cli -- push myapp/production --file .env.production
+# 6. Push a vault — the pusher is automatically its first recipient
+keep push myapp/production --file .env.production
 
-# 6. Anyone else with a grant can pull it, decrypted, ready to use
-npm run cli -- pull myapp/production > .env
+# 7. Anyone else with a grant can pull it, decrypted, ready to use
+keep pull myapp/production > .env
 ```
 
 ## Granting, revoking, rotating
diff --git a/scripts/install-cli.sh b/scripts/install-cli.sh
new file mode 100755
index 0000000..939853b
--- /dev/null
+++ b/scripts/install-cli.sh
@@ -0,0 +1,23 @@
+#!/bin/sh
+# Builds keep and symlinks the CLI onto PATH as a real `keep` command --
+# no `npm run cli --` from inside this repo, no npm global install (which
+# needs root/write access to the system Node install on most hosts).
+#
+# Since this is a symlink to dist/cli/index.js rather than a copy, a
+# future `git pull && npm run build` here is the entire upgrade story --
+# no need to re-run this script.
+set -eu
+cd "$(dirname "$0")/.."
+
+BIN_DIR="${KEEP_BIN_DIR:-$HOME/.local/bin}"
+mkdir -p "$BIN_DIR"
+
+npm run build
+chmod +x dist/cli/index.js
+ln -sf "$(pwd)/dist/cli/index.js" "$BIN_DIR/keep"
+
+echo "keep CLI linked: $BIN_DIR/keep -> $(pwd)/dist/cli/index.js"
+case ":$PATH:" in
+  *":$BIN_DIR:"*) echo "$BIN_DIR is already on PATH — try: keep --help" ;;
+  *) echo "warning: $BIN_DIR is not on PATH — add it to your shell profile" ;;
+esac