@kleo.so/cli 1.0.0 → 1.1.1

package/README.md

@@ -6,31 +6,41 @@ The Kleo CLI lets you work with your Kleo workspace from the terminal. You can r
 
 The CLI is a small client for the Model Context Protocol (MCP). When you run a command, it opens a session with Kleo's own MCP server at `/api/mcp/mcp`, calls one of the tools that server exposes, and prints the result. Those tools are the same ones the web app, the WhatsApp agent, and the Claude and Cursor connectors use, so the CLI does not reimplement any of that logic. It only sends requests and formats what comes back.
 
-Every request carries your API key as a bearer token. Because the CLI talks to the server over the network, it never touches the database or any server secret. All it needs is your key and the address of the server.
+Every request carries a Clerk OAuth access token as a bearer token — the same auth mechanism the Claude Code and Cursor connectors use, obtained via a normal browser sign-in rather than a copy-pasted secret. Because the CLI talks to the server over the network, it never touches the database or any server secret.
 
 ## Requirements
 
 You need Node.js version 18 or later. The server you connect to must have the MCP feature enabled, which means it was deployed with `NEXT_PUBLIC_ENABLE_MCP=true`.
 
-## Getting an API key
-
-Sign in to Kleo, open Settings, and go to the MCP section to create a key. You can also create one by sending a POST request to `/api/mcp/keys` while signed in. A key looks like `kleo_sk_` followed by a long random string. Each key carries a read scope, a write scope, or both, and the full value is shown only once, so copy it when it appears.
-
-Read commands such as `kb`, `swipe`, `template`, `post`, `memory`, `strategy`, and `whoami` need a key with the read scope. The `agent` command and any command that writes data need a key with both the read and write scopes. If a key is missing a scope, the server returns a clear message telling you which scope the tool requires.
-
 ## Installing
 
 Most people do not need to install anything. If you have Node.js, you can run the CLI straight from npm:
 
 ```bash
-npx @kleo.so/cli login --key kleo_sk_yourkey
-npx @kleo.so/cli kb list
+npx "@kleo.so/cli" login
+npx "@kleo.so/cli" kb list
+```
+
+If you use the CLI often, install it once so that the `kleo` command is always available.
+
+On Windows, open PowerShell, Command Prompt, or Git Bash:
+
+```powershell
+npm install -g "@kleo.so/cli"
 ```
 
-If you use the CLI often, install it once so that the `kleo` command is always available:
+Keep the quotes around `"@kleo.so/cli"` in PowerShell so it treats it as a package name. The quoted command also works in Command Prompt and Git Bash.
+
+On macOS, open Terminal. On Linux, open your terminal:
 
 ```bash
 npm install -g @kleo.so/cli
+```
+
+Then sign in and check the connection on any operating system:
+
+```bash
+kleo login
 kleo whoami
 ```
 
@@ -38,15 +48,17 @@ If you are working inside this repository instead of the published package, run
 
 ## Signing in
 
-Save your key and, if needed, the server address with the `login` command. This writes a small configuration file to `~/.kleo/config.json` with permissions set so that only you can read it.
+Run `kleo login`. It opens your browser to Kleo's sign-in page (Clerk OAuth 2.1 with PKCE); once you approve, the CLI receives an access token and a refresh token and writes them to `~/.kleo/config.json` with permissions set so that only you can read it. Tokens refresh automatically as they expire — you only need to run `login` again if you explicitly `logout` or the session is revoked.
+
+Keep the terminal open while you sign in and approve access in the browser. If the browser does not open, copy the full URL printed by `kleo login` into your browser. Wait for the terminal to confirm that you are signed in, then run `kleo whoami` to check the connection. If login times out, run `kleo login` again and use the new URL.
 
 ```bash
-kleo login --key kleo_sk_yourkey --url https://app.kleo.so
+kleo login [--url https://app.kleo.so]
 ```
 
 The server address defaults to `https://app.kleo.so`. When you are pointing at a local development server, pass `--url http://localhost:3000` instead.
 
-The CLI decides which key and address to use by checking four sources in order and taking the first one it finds. It starts with the `--key` and `--url` flags on the command line. If those are absent, it reads the `KLEO_API_KEY` and `KLEO_API_URL` environment variables. If those are also absent, it reads the configuration file written by `login`. If nothing else is set, it falls back to the default address. This means you can keep a key in the config file for everyday use and still override it for a single command with a flag or an environment variable.
+The CLI decides which server address to use by checking three sources in order and taking the first one it finds: the `--url` flag, the `KLEO_API_URL` environment variable, then the address saved by `login`. If nothing else is set, it falls back to the default address.
 
 ## Commands
 
@@ -54,10 +66,10 @@ The command reference below groups the commands by area. Angle brackets mark val
 
 ```
 Account
-  kleo login --key <key> [--url <url>]   Save your key and server address
-  kleo logout                            Remove the saved credentials
-  kleo config                            Show the current server and a masked key
-  kleo whoami                            Show the user and profile the key acts as
+  kleo login [--url <url>]               Sign in via browser and save the session
+  kleo logout                            Remove the saved session
+  kleo config                            Show the current server and session status
+  kleo whoami                            Show the user and profile this session acts as
 
 Knowledge base
   kleo kb list                           List every item with its id, title, type, and a short preview
@@ -92,7 +104,7 @@ Agent and direct tool access
   kleo call <tool> [--input '<json>'] [key=value ...]   Call any tool by name
 ```
 
-Several flags apply to any command. Use `--url` and `--key` to override the saved server address and key for a single run. Use `--limit` to cap how many results a list or search returns. Use `--json` to print the raw response instead of formatted text, which is useful when you pipe the output into another tool. Use `-h` or `--help` to see the built in help.
+Several flags apply to any command. Use `--url` to override the saved server address for a single run. Use `--limit` to cap how many results a list or search returns. Use `--json` to print the raw response instead of formatted text, which is useful when you pipe the output into another tool. Use `-h` or `--help` to see the built in help.
 
 ## Examples