Clarify raw API key rotation policy

Author: dannyshmueli

README.md

@@ -63,10 +63,11 @@ experiments complete <id>        Ship the winner
 whoami                           Show current account & tier
 feedback --message "..."         Send product/process feedback
 logout                           Clear saved local auth (does not revoke remote sessions)
-revoke-key                       Revoke and regenerate API key
+revoke-key                       Rotate a saved raw API key fallback
 ```
 
 The CLI is agent-session-first. It stores a renewable Agent Analytics session locally after browser approval and uses that bearer auth for API calls. Raw `aak_*` API keys still work, but only as an advanced/manual fallback for direct HTTP-style usage.
+Raw API-key rotation is not available to scoped agent sessions; manage keys from the dashboard or from a CLI login created with `login --token`.
 
 Bounce metrics (`insights`, `pages`, `sessions`) treat a session as a bounce when it has only non-interactive events:
 `page_view`, `$impression`, `$scroll_depth`, `$error`, `$time_on_page`, `$performance`, `$web_vitals`.

bin/cli.mjs

@@ -935,8 +935,23 @@ function cmdDeleteAccount() {
   log('');
 }
 
-const cmdRevokeKey = withApi(async (api) => {
-  const data = await api.revokeKey();
+async function cmdRevokeKey() {
+  const auth = getStoredAuth();
+  if (!auth) {
+    error('Not logged in. Run: npx @agent-analytics/cli login --token <api-key>');
+  }
+  if (auth.access_token || auth.refresh_token) {
+    error('revoke-key only rotates a saved raw API key. Manage API keys from https://app.agentanalytics.sh/settings or log in with --token for the API-key fallback.');
+  }
+
+  const api = createApiClient(auth);
+  let data;
+  try {
+    data = await api.revokeKey();
+  } catch (err) {
+    error(err.message);
+  }
+
   setApiKey(data.api_key);
 
   warn('Old API key revoked');
@@ -945,7 +960,7 @@ const cmdRevokeKey = withApi(async (api) => {
   log(`${YELLOW}${data.api_key}${RESET}`);
   log(`${DIM}Saved to ${getConfigFile()}${RESET}\n`);
   warn('Update your agent with this new key!');
-});
+}
 
 const cmdFeedback = withApi(async (api, opts = {}) => {
   if (!opts.message) {
@@ -1265,7 +1280,7 @@ ${BOLD}EXPERIMENTS${RESET} ${DIM}— A/B testing your agent can actually use${RE
 
 ${BOLD}ACCOUNT${RESET}
   ${CYAN}whoami${RESET}                 Show current account & tier
-  ${CYAN}revoke-key${RESET}             Revoke and regenerate API key
+  ${CYAN}revoke-key${RESET}             Rotate a saved raw API key fallback
   ${CYAN}feedback${RESET}               Send product/process feedback
   ${CYAN}project${RESET} <id>           Get single project details
   ${CYAN}update${RESET} <id>            Update a project (--name, --origins)