From 2e49e18c9b80254fc401730adc9d61e028b615e6 Mon Sep 17 00:00:00 2001
From: Sergey Aldoukhov <saldoukhov@gmail.com>
Date: Wed, 26 Aug 2026 11:58:53 -0700
Subject: [PATCH] repl related readmes

---
 KeeperSdk/README.md     |  4 +++
 README.md               | 12 +++++++-
 examples/repl/README.md | 67 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 examples/repl/README.md

diff --git a/KeeperSdk/README.md b/KeeperSdk/README.md
index 3fb52034..5894094c 100644
--- a/KeeperSdk/README.md
+++ b/KeeperSdk/README.md
@@ -429,6 +429,9 @@ Most examples call the shared `login()` helper, which attempts persistent login
 
 See [`examples/sdk_example/README.md`](../examples/sdk_example/README.md) for the full command list.
 
+Prefer an interactive shell over one-off scripts? See [`examples/repl`](../examples/repl/README.md)
+for a REPL that logs in once and runs vault commands (`ls`, `cd`, `get`, `find`, …) until you exit.
+
 ---
 
 ## Development Setup
@@ -467,6 +470,7 @@ keeper-sdk-javascript/
 ├── keeperapi/                 # @keeper-security/keeperapi
 └── examples/
     ├── sdk_example/           # Runnable Node scripts (auth, records, folders, …)
+    ├── repl/                  # Interactive vault shell
     ├── print-vault-node/      # Additional Node sample
     └── print-vault-browser/   # Browser sample
 ```
diff --git a/README.md b/README.md
index cce3ad21..5f5f98b1 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,8 @@ keeper-sdk-javascript/
 ├── KeeperSdk/              # @keeper-security/keeper-sdk-javascript
 ├── keeperapi/              # @keeper-security/keeperapi
 └── examples/
-    └── sdk_example/        # Runnable Node scripts (auth, records, folders, …)
+    ├── sdk_example/        # Runnable Node scripts (auth, records, folders, …)
+    └── repl/               # Interactive vault shell (see examples/repl/README.md)
 ```
 
 **Start here for CLI / vault behavior:** [`KeeperSdk/README.md`](KeeperSdk/README.md) — built-in commands, `get` / `whoami` output, and `KeeperCliHost` adapter requirements.
@@ -46,6 +47,15 @@ npm run auth:restore-session -- --from-json /path/to/session.json
 npm run records:list:shell-cli -- --from-json /path/to/session.json
 ```
 
+Or jump into the interactive vault REPL (needs `KeeperSdk` linked via `npm run link-local` above):
+
+```bash
+cd examples/repl && npm install
+npm start
+```
+
+See [`examples/repl/README.md`](examples/repl/README.md) for the command list.
+
 ## Package docs
 
 - [`KeeperSdk/README.md`](KeeperSdk/README.md) — API, CLI commands, host adapter
diff --git a/examples/repl/README.md b/examples/repl/README.md
new file mode 100644
index 00000000..2281e60c
--- /dev/null
+++ b/examples/repl/README.md
@@ -0,0 +1,67 @@
+# Keeper Vault REPL
+
+An interactive shell for the Keeper Vault: log in once, then run `ls`, `cd`, `get`, `find`, and
+other commands against your vault until you exit.
+
+## Prerequisites
+
+- Node.js 20 LTS or newer
+- A Keeper account with credentials
+
+## Setup
+
+This example depends on the sibling `KeeperSdk` and `keeperapi` packages by local path
+(`file:../../KeeperSdk`, `file:../../keeperapi`), so those need to be built once before the REPL
+can resolve `@keeper-security/keeperapi` at runtime:
+
+```bash
+# From the repository root
+cd keeperapi && npm install && npm run build
+cd ../KeeperSdk && npm install && npm run link-local && npm run build
+
+# Now the REPL itself
+cd ../examples/repl
+npm install
+```
+
+## Run
+
+```bash
+npm start
+```
+
+There's no config file to set up first — on first run you'll be prompted interactively for
+server, username, and password. Credentials/session are then saved to `~/.keeper/config.json` for
+persistent login on subsequent runs (same file used by the other examples in this repo).
+
+## Commands
+
+Type `help` inside the REPL for the live list. Summary:
+
+| Command | Description |
+|---|---|
+| `help` | List available commands |
+| `whoami` | Show current session info |
+| `pwd` | Print current working folder |
+| `ls [path]` | List contents of the current (or given) folder |
+| `cd [path]` | Change the current working folder (`cd /` for vault root) |
+| `tree [path]` | Show the folder tree from the current (or given) folder |
+| `list` | List every record in the vault |
+| `find <text>` | Search records by title, login, or URL |
+| `get <uid\|title>` | Show details for a single record |
+| `sync` | Re-sync the vault with the server |
+| `get_controllers` | Call the PAM router API (`pam/get_controllers`) and list enterprise gateways |
+| `get_online_controllers` | Call the PAM router API (`loadOnlineControllers`) and list connected gateways |
+| `run <script.ts> [args...]` | Execute a TypeScript file exporting `default async function(vault, args)` — see [`scripts/README.md`](scripts/README.md) |
+| `history` | Show command history |
+| `clear` | Clear the screen |
+| `exit` / `quit` | Log out and quit the REPL |
+
+Command history persists across sessions in `~/.keeper/repl_history` (excluding `history`, `exit`,
+`quit`, `clear`); use `!<n>` to re-run entry `n` from `history`, bash-style.
+
+## Extending
+
+Drop a `.ts` file under [`scripts/`](scripts/README.md) and run it with `run scripts/<file>.ts` for
+one-off tasks against the live, authenticated `vault` — no rebuild needed. Promote anything that
+turns out to be a permanent command into `src/commands.ts`.