kenso 0.1.10 → 0.1.12

package/README.md

@@ -18,14 +18,18 @@ Or without installing: `npx kenso --help`.
 
 ## Log in
 
-Create an API key in app.ken.so at Settings > Integrations > API keys, then:
+```bash
+kenso auth login
+```
+
+The CLI prints a link and a code. Open the link, check the code, pick the workspace and approve: the CLI saves a new API key for it.
+
+For CI and scripts, create an API key in app.ken.so at Settings > Integrations > API keys and pipe it in, or set `KENSO_API_KEY` in their environment and skip the login:
 
 ```bash
 echo $KEY | kenso auth login --with-key
 ```
 
-That is also the way in for CI and agents, or set `KENSO_API_KEY` in their environment and skip the login. Browser login (`kenso auth login`) works when your workspace has it; until then it points you to `--with-key`.
-
 ## 60-second quickstart
 
 ```bash

package/dist/kenso.js

@@ -2397,7 +2397,7 @@ var VERSION;
 var init_version = __esm({
   "src/core/version.ts"() {
     "use strict";
-    VERSION = true ? "0.1.10" : "0.0.0-dev";
+    VERSION = true ? "0.1.12" : "0.0.0-dev";
   }
 });
 
@@ -7149,7 +7149,7 @@ async function browserLogin(ctx, opts, overrides) {
     if (err instanceof KensoError && err.httpStatus === 404) {
       throw new KensoError({
         code: "browser_login_unavailable",
-        message: "Browser login is not available yet.",
+        message: "Browser login is turned off on this Kenso API.",
         exitCode: ExitCode.Auth,
         httpStatus: 404,
         hint: "Create an API key in app.ken.so at Settings > Integrations > API keys",
@@ -9440,7 +9440,7 @@ var init_agents = __esm({
 var auth_default;
 var init_auth2 = __esm({
   "docs/auth.md"() {
-    auth_default = '# Authentication\n\nThe CLI calls the Kenso API with a Kenso API key (`ken_` plus 43 characters). It sends the key as `Authorization: Bearer <key>` and never prints it, logs it or puts it in an error.\n\n## Log in with an API key\n\n1. In app.ken.so, go to Settings > Integrations > API keys and create a key.\n2. Pipe it to `kenso auth login --with-key`. The key is read from stdin, never from a flag, so it stays out of your shell history and process list.\n\n```bash\necho $KEY | kenso auth login --with-key\nkenso auth login --with-key --profile client-a --workspace 1234 < key.txt\n```\n\nThe CLI checks the key with `GET /v1/me`, then saves it to `~/.kenso/config.json` (file mode 0600, folder mode 0700). It prints:\n\n```json\n{"profile":"default","email":"you@acme.io","workspaceId":"1234","workspaceCount":1}\n```\n\nWhen the key reaches several workspaces and you did not pass `--workspace`, no workspace is saved and the output carries `"next":"kenso workspace list --q <name>"`. A key in the wrong format exits 2 (`invalid_key_format`). A key Kenso rejects exits 3.\n\n## Browser login\n\n```bash\nkenso auth login\nkenso auth login --no-browser --device-name "build box"\n```\n\nBrowser login is rolling out. Until it is on for your account, `kenso auth login` answers `browser_login_unavailable` (exit 3) with `"next":"kenso auth login --with-key"`: use an API key as above.\n\nWhen your workspace has it, the CLI prints a link and a code on stderr. You open the link, check the code and approve. The CLI then saves a new API key to the profile, the same kind you create in the app: it shows in your API key list, where you can revoke it. The CLI opens the browser itself only when no coding agent is detected and the machine has a display. An agent prints the link and asks you to open it. The login expires after 10 minutes (`login_expired`, exit 3), and a denied login exits 3 with `access_denied`.\n\n## CI, scripts and agents: use the environment\n\nYou do not need to log in on a machine that has the key in its environment:\n\n```bash\nexport KENSO_API_KEY=ken_...\nexport KENSO_WORKSPACE_ID=1234\nkenso auth status\n```\n\n`KENSO_API_KEY` wins over any saved profile. Store it as a secret in your CI or agent platform, never in a file in the repo.\n\n## Workspaces\n\nA key reaches every workspace its user belongs to. Each command runs in one workspace, picked in this order:\n\n1. `--workspace <id>` on the command\n2. `KENSO_WORKSPACE_ID`\n3. the workspace saved in the profile (`kenso workspace use`)\n\n```bash\nkenso workspace list --q acme\nkenso workspace use 1234\nkenso campaigns list --workspace 5678\n```\n\n`workspace list` prints one page and says on stderr when there are more: add `--all` for every page. A command that needs a workspace when none is picked fails with `workspace_required` (exit 2) and `"next":"kenso workspace list --q <name>"`.\n\n## Profiles\n\nA profile holds a key, a workspace, an optional API URL and the email. Use one per client or per key:\n\n```bash\nkenso auth login --with-key --profile client-a < client-a-key.txt\nkenso campaigns list --profile client-a\nKENSO_PROFILE=client-a kenso auth status\n```\n\nThe profile is `--profile`, else `KENSO_PROFILE`, else the active one (the last one you logged in to).\n\n## Check the setup\n\n```bash\nkenso auth status\nkenso doctor\n```\n\n`auth status` prints who the key belongs to and when it expires, and warns on stderr when that is within 14 days:\n\n```json\n{"email":"you@acme.io","workspaceCount":3,"activeWorkspace":{"id":"1234","name":"Acme"},"keyExpiresAt":"2027-01-31T00:00:00Z","keySource":"profile","profile":"default"}\n```\n\n`doctor` prints the version, Node, the config folder, the profile, the key source, the API URL, the workspace and the detected agent, then four checks: `node_version`, `config_permissions`, `api_reachable` and `key_valid`. It exits 0 when every check passes, 3 when the key is missing or rejected, else 1.\n\n## Log out\n\n```bash\nkenso auth logout\nkenso auth logout --profile client-a\n```\n\nThis removes the profile and its key from this machine. The key itself stays valid until you revoke it at Settings > Integrations > API keys.\n\n## Where things live\n\n| What | Default | Override |\n|---|---|---|\n| Config file with profiles and keys | `~/.kenso/config.json` | `KENSO_CONFIG_DIR` |\n| Run folders | `~/.kenso/runs/` | `KENSO_RUNS_DIR` |\n| Cached workspace features (1 hour) | `~/.kenso/cache/` | follows `KENSO_CONFIG_DIR` |\n| API | `https://api.ken.so` | `KENSO_API_URL` |\n| MCP (for `kenso mcp`) | `https://mcp.ken.so/mcp` | `KENSO_MCP_URL` |\n\n`--verbose` prints each request line to stderr with the key redacted.\n';
+    auth_default = '# Authentication\n\nThe CLI calls the Kenso API with a Kenso API key (`ken_` plus 43 characters). It sends the key as `Authorization: Bearer <key>` and never prints it, logs it or puts it in an error.\n\n## Log in with an API key\n\n1. In app.ken.so, go to Settings > Integrations > API keys and create a key.\n2. Pipe it to `kenso auth login --with-key`. The key is read from stdin, never from a flag, so it stays out of your shell history and process list.\n\n```bash\necho $KEY | kenso auth login --with-key\nkenso auth login --with-key --profile client-a --workspace 1234 < key.txt\n```\n\nThe CLI checks the key with `GET /v1/me`, then saves it to `~/.kenso/config.json` (file mode 0600, folder mode 0700). It prints:\n\n```json\n{"profile":"default","email":"you@acme.io","workspaceId":"1234","workspaceCount":1}\n```\n\nWhen the key reaches several workspaces and you did not pass `--workspace`, no workspace is saved and the output carries `"next":"kenso workspace list --q <name>"`. A key in the wrong format exits 2 (`invalid_key_format`). A key Kenso rejects exits 3.\n\n## Browser login\n\n```bash\nkenso auth login\nkenso auth login --no-browser --device-name "build box"\n```\n\nBrowser login is available to every workspace. The CLI prints a link and a code on stderr. You open the link, sign in to app.ken.so, check that the code matches the one in your terminal, pick the workspace to start in and approve. The CLI then saves a new API key to the profile and prints:\n\n```json\n{"profile":"default","email":"you@acme.io","workspaceId":"1234","keyExpiresAt":"2027-02-02T06:26:59Z"}\n```\n\nThe key is the same kind you create in the app. It is named `Kenso CLI - <device name>` (`--device-name`, else `kenso-cli on <hostname>`), lasts 90 days, and shows in your API key list at Settings > Integrations > API keys, where you can revoke it. The CLI opens the browser itself only when no coding agent is detected and the machine has a display. An agent prints the link and asks you to open it. The login expires after 10 minutes (`login_expired`, exit 3), and a denied login exits 3 with `access_denied`. If the API answers that browser login is off (`browser_login_unavailable`, exit 3, `"next":"kenso auth login --with-key"`), log in with an API key as above.\n\n## CI, scripts and agents: use the environment\n\nYou do not need to log in on a machine that has the key in its environment:\n\n```bash\nexport KENSO_API_KEY=ken_...\nexport KENSO_WORKSPACE_ID=1234\nkenso auth status\n```\n\n`KENSO_API_KEY` wins over any saved profile. Store it as a secret in your CI or agent platform, never in a file in the repo.\n\n## Workspaces\n\nA key reaches every workspace its user belongs to. Each command runs in one workspace, picked in this order:\n\n1. `--workspace <id>` on the command\n2. `KENSO_WORKSPACE_ID`\n3. the workspace saved in the profile (`kenso workspace use`)\n\n```bash\nkenso workspace list --q acme\nkenso workspace use 1234\nkenso campaigns list --workspace 5678\n```\n\n`workspace list` prints one page and says on stderr when there are more: add `--all` for every page. A command that needs a workspace when none is picked fails with `workspace_required` (exit 2) and `"next":"kenso workspace list --q <name>"`.\n\n## Profiles\n\nA profile holds a key, a workspace, an optional API URL and the email. Use one per client or per key:\n\n```bash\nkenso auth login --with-key --profile client-a < client-a-key.txt\nkenso campaigns list --profile client-a\nKENSO_PROFILE=client-a kenso auth status\n```\n\nThe profile is `--profile`, else `KENSO_PROFILE`, else the active one (the last one you logged in to).\n\n## Check the setup\n\n```bash\nkenso auth status\nkenso doctor\n```\n\n`auth status` prints who the key belongs to and when it expires, and warns on stderr when that is within 14 days:\n\n```json\n{"email":"you@acme.io","workspaceCount":3,"activeWorkspace":{"id":"1234","name":"Acme"},"keyExpiresAt":"2027-01-31T00:00:00Z","keySource":"profile","profile":"default"}\n```\n\n`doctor` prints the version, Node, the config folder, the profile, the key source, the API URL, the workspace and the detected agent, then four checks: `node_version`, `config_permissions`, `api_reachable` and `key_valid`. It exits 0 when every check passes, 3 when the key is missing or rejected, else 1.\n\n## Log out\n\n```bash\nkenso auth logout\nkenso auth logout --profile client-a\n```\n\nThis removes the profile and its key from this machine. The key itself stays valid until you revoke it at Settings > Integrations > API keys.\n\n## Where things live\n\n| What | Default | Override |\n|---|---|---|\n| Config file with profiles and keys | `~/.kenso/config.json` | `KENSO_CONFIG_DIR` |\n| Run folders | `~/.kenso/runs/` | `KENSO_RUNS_DIR` |\n| Cached workspace features (1 hour) | `~/.kenso/cache/` | follows `KENSO_CONFIG_DIR` |\n| API | `https://api.ken.so` | `KENSO_API_URL` |\n| MCP (for `kenso mcp`) | `https://mcp.ken.so/mcp` | `KENSO_MCP_URL` |\n\n`--verbose` prints each request line to stderr with the key redacted.\n';
   }
 });