feat: add privacy-first email lookup CLI

Author: dannyshmueli

README.md

@@ -9,10 +9,10 @@ Analytics your AI agent can actually use — track, analyze, experiment, optimiz
 Try the seeded public demo without signing in:
 
 ```bash
-npx --yes @agent-analytics/cli@0.5.20 demo
-npx --yes @agent-analytics/cli@0.5.20 --demo projects
-npx --yes @agent-analytics/cli@0.5.20 --demo funnel agentanalytics-demo --steps "page_view,signup_started,signup"
-npx --yes @agent-analytics/cli@0.5.20 --demo experiments list agentanalytics-demo
+npx --yes @agent-analytics/cli@0.5.24 demo
+npx --yes @agent-analytics/cli@0.5.24 --demo projects
+npx --yes @agent-analytics/cli@0.5.24 --demo funnel agentanalytics-demo --steps "page_view,signup_started,signup"
+npx --yes @agent-analytics/cli@0.5.24 --demo experiments list agentanalytics-demo
 ```
 
 Demo mode fetches a short-lived read-only `aas_*` session from the hosted API. It does not expose a raw `aak_*` API key, does not write local CLI config, and blocks mutating commands before making API requests.
@@ -21,19 +21,19 @@ Get the fastest path to useful analytics before installing events:
 
 ```bash
 # 1. Preview what your agent should track first
-npx --yes @agent-analytics/cli@0.5.20 scan https://mysite.com --json
+npx --yes @agent-analytics/cli@0.5.24 scan https://mysite.com --json
 
 # 2. Sign in when you want the full instrumentation plan
-npx --yes @agent-analytics/cli@0.5.20 login
+npx --yes @agent-analytics/cli@0.5.24 login
 
 # 3. Create or identify the project domain
-npx --yes @agent-analytics/cli@0.5.20 create my-site --domain https://mysite.com
+npx --yes @agent-analytics/cli@0.5.24 create my-site --domain https://mysite.com
 
 # 4. Run the full signed-in analysis for that project domain
-npx --yes @agent-analytics/cli@0.5.20 scan https://mysite.com --full --project my-site --json
+npx --yes @agent-analytics/cli@0.5.24 scan https://mysite.com --full --project my-site --json
 
 # Or resume and upgrade the anonymous analysis after login
-npx --yes @agent-analytics/cli@0.5.20 scan \
+npx --yes @agent-analytics/cli@0.5.24 scan \
   --resume <analysis_id> \
   --resume-token <resume_token> \
   --full \
@@ -45,19 +45,19 @@ Anonymous `scan` returns a one-analysis `rst_*` resume token, not an `aas_*` age
 
 ```bash
 # 1. Start agent login or signup in the browser
-npx --yes @agent-analytics/cli@0.5.20 login
+npx --yes @agent-analytics/cli@0.5.24 login
 
 # 2. Create a project
-npx --yes @agent-analytics/cli@0.5.20 create my-site --domain https://mysite.com
+npx --yes @agent-analytics/cli@0.5.24 create my-site --domain https://mysite.com
 
 # 3. Watch it live
-npx --yes @agent-analytics/cli@0.5.20 live
+npx --yes @agent-analytics/cli@0.5.24 live
 
 # Optional detached login for remote or issue-based agent work
-npx --yes @agent-analytics/cli@0.5.20 login --detached
+npx --yes @agent-analytics/cli@0.5.24 login --detached
 
 # Optional: clear your saved local auth later
-npx --yes @agent-analytics/cli@0.5.20 logout
+npx --yes @agent-analytics/cli@0.5.24 logout
 ```
 
 ## Commands
@@ -110,6 +110,12 @@ context set <name> --json '{...}' Store compact goals, activation events, glossa
 portfolio-context get            Read stored account portfolio context
 portfolio-context set --json '{...}'
                                  Store shared goals, surface roles, milestones, and glossary
+portfolios list                  List identity lookup portfolios
+portfolios create <slug> --name "Portfolio" --projects app,docs [--move]
+                                 Create a project portfolio; --move allows reassigning projects
+portfolios get <slug-or-id>      Show a portfolio and its member projects
+portfolios update <slug-or-id>   Update name and/or projects with optional --move
+portfolios delete <slug-or-id>   Delete a portfolio
 
 # Experiments — A/B testing your agent can actually use
 experiments list <project>       List experiments
@@ -128,17 +134,17 @@ The CLI is agent-session-first. It stores a renewable Agent Analytics session lo
 When a free account hits a Pro-only analytics task, run an explicit upgrade handoff:
 
 ```bash
-npx --yes @agent-analytics/cli@0.5.20 upgrade-link --detached \
+npx --yes @agent-analytics/cli@0.5.24 upgrade-link --detached \
   --reason "Need funnel and retention reads for this analysis" \
-  --command "npx --yes @agent-analytics/cli@0.5.20 funnel my-site --steps page_view,signup,purchase"
+  --command "npx --yes @agent-analytics/cli@0.5.24 funnel my-site --steps page_view,signup,purchase"
 ```
 
 The CLI prints an `app.agentanalytics.sh` link. The human confirms the logged-in dashboard account, pays in Lemon Squeezy, and returns to the agent after Pro activates. Use `upgrade-link --wait` when the local shell should keep polling for activation.
 
 Project management commands accept exact project names or project IDs. For local browser QA, update origins through the CLI while keeping the production origin:
 
 ```bash
-npx --yes @agent-analytics/cli@0.5.20 update stylio --origins 'https://stylio.app,http://lvh.me:3101'
+npx --yes @agent-analytics/cli@0.5.24 update stylio --origins 'https://stylio.app,http://lvh.me:3101'
 ```
 
 Use `scan` before tracker installation when you want judgment instead of generic event lists. The preview is intentionally small: prioritized minimum viable instrumentation, what each event unlocks, current blind spots, and what not to track yet. The stable JSON is designed for agent skills to install only the high-priority events first and verify the first useful recommended event.
@@ -151,27 +157,29 @@ Bounce metrics (`insights`, `pages`, `sessions`) treat a session as a bounce whe
 `query` keeps `/events` raw and lossless, but `/query` uses activation-safe dedupe (`session_then_user`) as the default for `event_count`: session-backed rows count by session, no-session rows fall back to `user_id` only when that user has no session-backed row in the same filtered/grouped result set, and fully anonymous rows fall back to event `id`. For recent signup or ingestion debugging, check `events <project> --event <actual_event_name>` first, then use `query` after verifying the raw event names the project emits. `--count-mode` only affects `event_count`. Use `--count-mode raw` when you need the old ingested-row count for debugging or audit work:
 
 ```bash
-npx --yes @agent-analytics/cli@0.5.20 query my-site --metrics event_count --count-mode raw
+npx --yes @agent-analytics/cli@0.5.24 query my-site --metrics event_count --count-mode raw
 ```
 
 Property filters must use canonical `properties.*` fields. Built-in filter fields are only `event`, `user_id`, `date`, `country`, `session_id`, and `timestamp`. Example:
 
 ```bash
-npx --yes @agent-analytics/cli@0.5.20 query my-site --filter '[{"field":"properties.referrer","op":"contains","value":"clawflows.com"}]'
+npx --yes @agent-analytics/cli@0.5.24 query my-site --filter '[{"field":"properties.referrer","op":"contains","value":"clawflows.com"}]'
 ```
 
 Invalid filter fields now fail loudly and return property discovery guidance instead of being silently ignored.
 
+Identity lookup with `--email` sends the normalized email to Agent Analytics over HTTPS for server-side project-scoped HMAC matching. The CLI no longer computes or sends a local `email_hash`; raw email is not stored in event rows or profile traits.
+
 Store compact project context when the product has custom goals, activation events, event meanings, or date annotations that should travel with analytics results. Keep this short because project-scoped analytics endpoints include it as `project_context`. `context set` accepts an encoded JSON body up to 512KB.
 
 Use annotations for major product changes that could explain later graph movement: landing page, pricing, onboarding, feature, release, or experiment changes. Do not store git commit logs, noisy edits, temporary metric notes, PII, secrets, or long release notes. Direct `context get` returns all annotations; project-scoped analytics responses include annotations only for the requested analytics date range plus one day before and after.
 
 Before setting or refreshing the glossary, inspect the project's current event names:
 
 ```bash
-npx --yes @agent-analytics/cli@0.5.20 properties my-site
-npx --yes @agent-analytics/cli@0.5.20 properties-received my-site
-npx --yes @agent-analytics/cli@0.5.20 context set my-site --json '{
+npx --yes @agent-analytics/cli@0.5.24 properties my-site
+npx --yes @agent-analytics/cli@0.5.24 properties-received my-site
+npx --yes @agent-analytics/cli@0.5.24 context set my-site --json '{
   "goals": ["Increase activated Agent Analytics accounts"],
   "activation_events": ["signup_completed", "project_created", "first_event_received"],
   "glossary": [
@@ -196,7 +204,7 @@ npx --yes @agent-analytics/cli@0.5.20 context set my-site --json '{
 Use the CLI feedback command when Agent Analytics was confusing, a task took too long, or the agent had to do manual analysis that the product should have handled:
 
 ```bash
-npx --yes @agent-analytics/cli@0.5.20 feedback \
+npx --yes @agent-analytics/cli@0.5.24 feedback \
   --message "The agent had to calculate the funnel drop-off manually" \
   --project my-site \
   --command "agent-analytics funnel my-site --steps page_view,signup,purchase" \
@@ -213,24 +221,24 @@ Claude Code, OpenClaw, Cursor, Codex — any AI agent that can run `npx`. Or add
 claude mcp add agent-analytics --transport http https://mcp.agentanalytics.sh/mcp
 ```
 
-For managed, issue-based, or remote runtimes that cannot receive a localhost callback or keep a long-running process alive, use `npx --yes @agent-analytics/cli@0.5.20 login --detached`. It prints the approval URL and exits. After browser approval, resume with the printed `login --auth-request <id> --exchange-code <code>` command.
+For managed, issue-based, or remote runtimes that cannot receive a localhost callback or keep a long-running process alive, use `npx --yes @agent-analytics/cli@0.5.24 login --detached`. It prints the approval URL and exits. After browser approval, resume with the printed `login --auth-request <id> --exchange-code <code>` command.
 
 For managed runtimes where the default home config path may not persist, point auth storage at a persistent runtime/workspace directory:
 
 ```bash
 export AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics"
-npx --yes @agent-analytics/cli@0.5.20 login --detached
-npx --yes @agent-analytics/cli@0.5.20 auth status
+npx --yes @agent-analytics/cli@0.5.24 login --detached
+npx --yes @agent-analytics/cli@0.5.24 auth status
 ```
 
 For one-off commands, use `--config-dir "$PWD/.openclaw/agent-analytics"` before or after the command. The CLI stores the same `config.json` file in that directory and does not migrate credentials from the default path.
 
-For a local shell where it is useful to keep waiting, use `npx --yes @agent-analytics/cli@0.5.20 login --detached --wait`.
+For a local shell where it is useful to keep waiting, use `npx --yes @agent-analytics/cli@0.5.24 login --detached --wait`.
 
 If your saved session predates CLI `0.5.9`, run a fresh login before calling `projects`. Older saved agent-session tokens were minted without `projects:read`, so they will keep failing until you re-authenticate. Verify with:
 
 ```bash
-npx --yes @agent-analytics/cli@0.5.20 projects
+npx --yes @agent-analytics/cli@0.5.24 projects
 ```
 
 ## Agent Skill

bin/cli.mjs

@@ -34,6 +34,8 @@
  *   npx @agent-analytics/cli context set <project> --json '{...}' — Set goals, activation events, glossary
  *   npx @agent-analytics/cli portfolio-context get — Get stored account portfolio context
  *   npx @agent-analytics/cli portfolio-context set --json '{...}' — Set goals, surface roles, milestones, glossary
+ *   npx @agent-analytics/cli portfolios list — List identity lookup portfolios
+ *   npx @agent-analytics/cli portfolios create <slug> --name "Portfolio" --projects app,docs [--move]
  *   npx @agent-analytics/cli update <name-or-id>   — Update a project
  *   npx @agent-analytics/cli delete <name-or-id>   — Delete a project
  *   npx @agent-analytics/cli live [name]          — Real-time live view
@@ -52,7 +54,6 @@
 
 import { AgentAnalyticsAPI } from '../lib/api.mjs';
 import { finishManualExchange, loginDetached, loginInteractive, startDetachedLogin } from '../lib/auth-flow.mjs';
-import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import {
   clearStoredAuth,
@@ -90,16 +91,10 @@ function normalizeEmail(email) {
   return String(email || '').trim().toLowerCase();
 }
 
-function hashEmail(email) {
-  const normalized = normalizeEmail(email);
-  if (!normalized) return null;
-  return createHash('sha256').update(normalized).digest('hex');
-}
-
 function identityOptions(opts = {}) {
   const out = {};
   if (opts.user_id) out.user_id = opts.user_id;
-  if (opts.email) out.email_hash = hashEmail(opts.email);
+  if (opts.email) out.email = normalizeEmail(opts.email);
   return out;
 }
 
@@ -1288,11 +1283,11 @@ const cmdQuery = withApi(async (api, project, opts = {}) => {
   --order-by  event_count, unique_users, session_count, date, event
   --order     asc or desc
   --limit     Max rows (default 100, max 1000)
-  --email     Filter by local-only normalized SHA-256 email hash lookup
+  --email     Filter by server-side scoped HMAC email lookup
 
 Property filters must use the canonical properties.<key> form.
 Example: properties.referrer, properties.utm_source, properties.first_utm_source
-Email lookup uses normalized SHA-256, not a keyed HMAC. It keeps raw email out of API requests but hashes may be guessable for known emails.
+Email lookup sends the email to Agent Analytics over HTTPS and matches with a project-scoped HMAC index. Raw email is not stored in event rows or profile traits.
 Invalid filter fields now fail loudly instead of being ignored.
 
 ${BOLD}Examples:${RESET}
@@ -1515,6 +1510,75 @@ const cmdPortfolioContext = withApi(async (subcommandApi, subcommand, opts = {})
   logPortfolioContext(data);
 });
 
+function parseProjectList(value) {
+  if (!value) return [];
+  return String(value).split(',').map((item) => item.trim()).filter(Boolean);
+}
+
+function logPortfolio(data) {
+  const portfolio = data?.portfolio || data;
+  if (!portfolio) {
+    log('No portfolio returned.');
+    return;
+  }
+  heading(`${portfolio.name || portfolio.slug} (${portfolio.slug || portfolio.id})`);
+  log(`${DIM}id:${RESET} ${portfolio.id}`);
+  const members = portfolio.members || [];
+  if (members.length === 0) {
+    log(`  ${DIM}No member projects.${RESET}`);
+    return;
+  }
+  for (const member of members) {
+    log(`  • ${member.project || member.project_id} ${DIM}${member.project_id}${RESET}`);
+  }
+}
+
+const cmdPortfolios = withApi(async (api, subcommand = 'list', target, opts = {}) => {
+  if (!['list', 'create', 'get', 'update', 'delete'].includes(subcommand)) {
+    error('Usage: npx @agent-analytics/cli portfolios <list|create|get|update|delete> [slug] [--name name] [--projects a,b] [--move]');
+  }
+
+  if (subcommand === 'list') {
+    const data = await api.listPortfolios();
+    const portfolios = data.portfolios || [];
+    if (portfolios.length === 0) {
+      log('No identity portfolios yet.');
+      return;
+    }
+    portfolios.forEach((portfolio) => log(`${portfolio.slug}\t${portfolio.name}\t${portfolio.id}`));
+    return;
+  }
+
+  if (subcommand === 'create') {
+    const slug = target || opts.slug;
+    if (!slug) error('Usage: npx @agent-analytics/cli portfolios create <slug> --name "Name" [--projects a,b]');
+    const data = await api.createPortfolio({ slug, name: opts.name || slug, projects: parseProjectList(opts.projects), allow_move: Boolean(opts.move) });
+    success(`Portfolio ${data.portfolio?.slug || slug} created`);
+    logPortfolio(data);
+    return;
+  }
+
+  if (!target) error(`Usage: npx @agent-analytics/cli portfolios ${subcommand} <slug-or-id>`);
+
+  if (subcommand === 'get') {
+    logPortfolio(await api.getPortfolio(target));
+    return;
+  }
+
+  if (subcommand === 'update') {
+    if (!opts.name && !opts.projects) error('Provide --name and/or --projects to update');
+    const data = await api.updatePortfolio(target, { name: opts.name, projects: opts.projects ? parseProjectList(opts.projects) : undefined, allow_move: Boolean(opts.move) });
+    success(`Portfolio ${data.portfolio?.slug || target} updated`);
+    logPortfolio(data);
+    return;
+  }
+
+  if (subcommand === 'delete') {
+    await api.deletePortfolio(target);
+    success(`Portfolio ${target} deleted`);
+  }
+});
+
 const cmdUpdate = withApi(async (api, target, opts = {}) => {
   if (!target) error('Usage: npx @agent-analytics/cli update <project-name-or-id> [--name new-name] [--origins "https://example.com"]');
   if (!opts.name && !opts.allowed_origins) error('Provide --name and/or --origins to update');
@@ -1938,6 +2002,11 @@ ${BOLD}ANALYTICS${RESET}
   ${CYAN}context set${RESET} <name>     Set compact project context with --json
   ${CYAN}portfolio-context get${RESET}  Read stored account portfolio context
   ${CYAN}portfolio-context set${RESET}  Set compact portfolio context with --json
+  ${CYAN}portfolios list${RESET}         List identity lookup portfolios
+  ${CYAN}portfolios create${RESET} <slug> Create a portfolio with --name and --projects
+  ${CYAN}portfolios get${RESET} <slug>   Show a portfolio and member projects
+  ${CYAN}portfolios update${RESET} <slug> Update name/projects with optional --move
+  ${CYAN}portfolios delete${RESET} <slug> Delete a portfolio
 
 ${BOLD}EXPERIMENTS${RESET} ${DIM}— A/B testing your agent can actually use${RESET}
   ${CYAN}experiments list${RESET} <project>     List experiments
@@ -1969,8 +2038,8 @@ ${BOLD}KEY OPTIONS${RESET}
   --property <key>   Property to break down (path, referrer, utm_source, country)
   --event <name>     Filter by event name
   --user-id <id>     Filter events or journeys to one known user id
-  --email <email>    Filter events, journeys, or query by local-only email hash lookup
-                     Uses normalized SHA-256, not a keyed HMAC; hashes may be guessable for known emails
+  --email <email>    Filter events, journeys, or query by server-side scoped HMAC email lookup
+                     Raw email is sent over HTTPS for lookup and is not stored in event rows or profile traits
   --message <text>   Feedback message for the product team
   --filter <json>    Filters for query (e.g. '[{"field":"country","op":"eq","value":"US"}]')
   --interval <N>     Live view refresh in seconds (default: 5)
@@ -2056,6 +2125,9 @@ function isDemoMutation(commandName, commandArgs) {
   if (commandName === 'context') {
     return commandArgs[1] === 'set';
   }
+  if (commandName === 'portfolios') {
+    return ['create', 'update', 'delete'].includes(commandArgs[1]);
+  }
   if (commandName === 'experiments') {
     return ['create', 'pause', 'resume', 'complete', 'delete'].includes(commandArgs[1]);
   }
@@ -2195,6 +2267,14 @@ try {
         json: getArg('--json'),
       });
       break;
+    case 'portfolios':
+      await cmdPortfolios(args[1] || 'list', args[2], {
+        slug: getArg('--slug'),
+        name: getArg('--name'),
+        projects: getArg('--projects'),
+        move: args.includes('--move'),
+      });
+      break;
     case 'update':
       await cmdUpdate(args[1], {
         name: getArg('--name'),