[DX-1114] Tag Web CLI traffic with a distinct Ably-Agent

[umair-ably]

Intent

We need to be able to split CLI usage tracking by the web cli vs "actual" cli usage

Summary

• Add getAgentName() helper in src/utils/version.ts that returns ably-web-cli when ABLY_WEB_CLI_MODE=true and ably-cli otherwise.
• Route the Ably SDK agents option (src/base-command.ts) and the Ably-Agent header on both the status check (src/commands/status.ts) and Control API requests (src/services/control-api.ts) through the new helper, so hosted Web CLI traffic is attributable separately from local CLI usage.
• Extend the agent-header unit test to cover both the default and Web CLI mode cases.

Test plan

• pnpm prepare
• pnpm exec eslint on changed files (0 errors)
• pnpm test test/unit/base-command/agent-header.test.ts (3 passed)

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
cli-web-cli	Ready	Preview, Comment	Apr 22, 2026 9:53am

[claude-code-ably-assistant]

Walkthrough

This PR introduces a getAgentName() helper that returns "ably-web-cli" when the ABLY_WEB_CLI_MODE environment variable is set, and "ably-cli" otherwise. All three places that set the Ably-Agent header or SDK agents option are routed through this helper, so Ably's analytics can attribute hosted Web CLI traffic separately from local CLI usage.

Changes

Area	Files	Summary
Utils	src/utils/version.ts	Added getAgentName() helper that reads ABLY_WEB_CLI_MODE via isWebCliMode() to resolve the correct agent name
Commands	src/base-command.ts	Routes SDK agents option through getAgentName() instead of hardcoded "ably-cli"
Commands	src/commands/status.ts	Routes Ably-Agent header in the status check through getAgentName()
Services	src/services/control-api.ts	Routes Ably-Agent header on all Control API requests through getAgentName()
Tests	test/unit/base-command/agent-header.test.ts	Adds Web CLI mode test case; switches beforeEach → afterEach to clean up ABLY_WEB_CLI_MODE env var

Review Notes

• Behavioral change: Any request made while ABLY_WEB_CLI_MODE=true will now send Ably-Agent: ably-web-cli/<version> instead of ably-cli/<version>. Confirm Ably's ingest pipeline accepts both agent names without filtering or validation errors.
• No new dependencies: reuses the existing isWebCliMode() helper from src/utils/web-mode.ts — no new packages added.
• Test coverage: the new branch in getAgentName() is covered by the updated unit test; status.ts and control-api.ts header paths are not separately tested but are trivial one-liners identical in structure to the already-tested base-command path.
• Env var cleanup: the test switches from beforeEach (empty) to afterEach that deletes ABLY_WEB_CLI_MODE — correct pattern to avoid leaking env state between tests.

[claude-code-ably-assistant]

Review Summary

File	Status	Notes
src/utils/version.ts	OK	Clean helper, consistent with isWebCliMode() pattern used elsewhere
src/base-command.ts	OK	SDK agents option correctly switched to dynamic key
src/commands/status.ts	OK	Ably-Agent header updated consistently
src/services/control-api.ts	OK	Ably-Agent header updated consistently
test/unit/base-command/agent-header.test.ts	OK	Both modes covered; afterEach cleanup is correct

No issues found

This is a clean, minimal change. The implementation correctly reads ABLY_WEB_CLI_MODE at call time (not at import time), so the agent name is resolved dynamically on every request — correct for env-var-driven mode switching. The abstraction through getAgentName() ensures all three callsites (SDK agents, status check header, Control API header) stay in sync automatically.

One pre-existing test oddity worth noting for future cleanup (not introduced by this PR): the "Version Format" describe block in agent-header.test.ts constructs `ably-cli/${version}` locally and checks its regex format, rather than calling getAgentName(). It always passes regardless of what getAgentName() returns, so it does not validate the Web CLI header format. Not a blocker — just worth a follow-up.

Ready to merge.

[sacOO7]

Btw, are we planning to deploy web CLI to ably domain, currently it's deployed on cli-web-cli.vercel.app

[lmars]

@umair-ably

Add getAgentName() helper in src/utils/version.ts that returns ably-web-cli when ABLY_WEB_CLI_MODE=true and ably-cli otherwise.

A couple of things:

• new agents should be added to agents.json so that we only aggregate known agent strings in stats
• this doesn't need to be either/or, I think the CLI should always use ably-cli/<cli version> as the primary entry, and we should add a subsequent entry which indicates the CLI is running in the Web CLI environment, so the full agent string might be ably-cli/0.17.0 ably-web-cli