[HDX-4129] CLI: support multiple teams and kubectx-style team switching

[wrn14897]

Summary

Adds kubectx-style team switching to @hyperdx/cli so users that belong to
multiple teams (HyperDX Cloud / EE) can scope CLI commands to any of their
teams without re-authenticating.

Three new commands under hdx team:

• hdx team list — lists every team the authenticated user belongs to, with
  the active team highlighted (▸).
• hdx team current — prints just the active team (handy in scripts).
• hdx team use <name-or-id> — switches the active team. Matches by team ID
  first, then falls back to case-insensitive name lookup. Errors out with the
  full list when no match is found.

Mechanics:

• SessionConfig gains an optional activeTeamId. It's persisted to
  ~/.config/hyperdx/cli/session.json alongside the cookies so the choice
  survives across CLI invocations.
• ApiClient injects an x-hdx-team header on every REST call when an
  active team is set. ProxyClickhouseClient does the same on the underlying
  ClickHouse-proxy request — both at construction time (initial header set)
  and per-query (so a mid-session change is picked up).
• getMe() now types teams?: MeTeam[]. EE's /api/me returns the array;
  OSS doesn't, so getUserTeams() falls back to a single-element list
  containing me.team.
• A successful auth login clears any previously persisted active team — the
  prior choice may not apply to a freshly authenticated user.
• hdx auth status now surfaces the active team alongside the email/server.

The header pattern matches the EE auth middleware
(packages/api/src/middleware/auth.ts)
and the existing browser app
(packages/app/src/api.ts addTeamHook).
On OSS the header is harmless — the OSS API has no multi-team support and
ignores it.

Screenshots or video

N/A — terminal CLI changes only.

How to test locally or on Vercel

Single-team (OSS) smoke test:

1. cd packages/cli && yarn build:common-utils && yarn dev auth login -a http://localhost:8080
2. yarn dev team list — should show one team with ▸ and a hint that
   team use is a no-op here.
3. yarn dev team current — should print the same team.
4. yarn dev team use <that-team-id> — should print "Switched to …".
5. yarn dev auth status — should now also show the team line.
6. Verify ~/.config/hyperdx/cli/session.json contains an activeTeamId
   field.
7. yarn dev sources — should still return the team's sources.
8. yarn dev auth login -a http://localhost:8080 -e ... -p ... — verify a
   fresh login resets activeTeamId to undefined in the session file.

Multi-team (EE) smoke test (requires hyperdx-ee deployment with a user
that has multiple team memberships):

1. yarn dev auth login -a https://your-ee-instance and authenticate.
2. yarn dev team list — both teams should be listed.
3. yarn dev team use <other-team-name> — switch.
4. yarn dev sources — should now return the other team's sources
   (the API receives x-hdx-team and scopes accordingly).

References

• Linear Issue: HDX-4129
• Related code: EE /api/me returns the teams array
  (hyperdx-ee/packages/api/src/routers/api/me.ts); EE auth middleware
  validates x-hdx-team against user membership
  (hyperdx-ee/packages/api/src/middleware/auth.ts).

[changeset-bot]

🦋 Changeset detected

Latest commit: f45681c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hyperdx/cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview, Comment	Apr 30, 2026 4:21am

[github-actions]

E2E Test Results

✅ All tests passed • 160 passed • 3 skipped • 1144s

Status	Count
✅ Passed	160
❌ Failed	0
⚠️ Flaky	3
⏭️ Skipped	3

Tests ran across 4 shards in parallel.

View full report →

[github-actions]

🟡 Tier 3 — Standard

Introduces new logic, modifies core functionality, or touches areas with non-trivial risk.

Why this tier:

• Standard feature/fix — introduces new logic or modifies core functionality

Review process: Full human review — logic, architecture, edge cases.
SLA: First-pass feedback within 1 business day.

Stats

• Production files changed: 3
• Production lines changed: 346
• Branch: warren/HDX-4129-cli-team-switching
• Author: wrn14897

To override this classification, remove the review/tier-3 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[github-actions]

PR Review

• ⚠️ Inconsistent "active team" fallback between team list and team current → team list falls back to teams[0]?.id when no activeTeamId is saved (cli.tsx ~line 578), while team current (via resolveActiveTeam) falls back to me.team. If teams[0] ≠ me.team, the ▸ marker in list and the output of current point to different teams. Align both to use the same fallback (likely me.team).

• ⚠️ No tests added → Project guidelines (AGENTS.md) require tests alongside implementation. Even a basic unit test for resolveActiveTeam and getUserTeams fallback logic would catch the inconsistency above and prevent regressions.

• ℹ️ Redundant x-hdx-team header in ProxyClickhouseClient → Header is set both at construction time (baseHeaders) and per-query. The comment explains why (mid-session team switches), but the constructor-level header is effectively dead weight since it's always overridden per-query when activeTeamId is set. Consider keeping only the per-query injection for clarity.

• ℹ️ AGENTS.md "Session Management" section outdated → Still says "Contains apiUrl and cookies[]" but activeTeamId is now a third field. Minor but someone reading docs will be confused.

• ℹ️ Changeset marked patch for a new feature → hdx team list/current/use are additive user-visible commands. Semver convention suggests minor. (May be intentional — the first commit message "bump cli changeset to patch" implies a deliberate choice.)