Add caller identification flag for telemetry (e.g. --user-agent)

[patrikbraborec]

Status

The CLI currently has no caller-identification flag or env var — the existing USER_AGENT in src/entrypoints/_shared.ts is the HTTP User-Agent string for API calls, which is unrelated.

Context

Split out from #1073 (Part 1, item 7) so it can be scoped and discussed on its own.

Agent Skills currently track usage via a hardcoded User-Agent header on API calls, e.g.:

const USER_AGENT = 'apify-agent-skills/apify-ultimate-scraper-1.3.0';

As Skills move from direct API calls to invoking the CLI (and as DX Heroes plugins for Claude Code, Cursor, OpenCode, etc. roll out), this monitoring breaks — there is no way for the CLI to tell whether a command came from a Skill, a plugin, or a human at a terminal.

The automatic ai_agent env var detection added in #1074 tells us which AI tool is running the CLI, but not which skill/plugin triggered the command.

Proposal

Add an opt-in, caller-provided identifier:

• New flag on all commands (working name: --user-agent), plus APIFY_CLI_USER_AGENT env var
• Example: apify actor call xyz --user-agent \"apify-agent-skills/ultimate-scraper-1.3.0\"
• Sent as a user_agent telemetry property alongside ai_agent
• Regular users don't pass it → null → direct CLI usage

This would give two independent tracking dimensions:

• ai_agent (auto) — which AI tool is running the CLI
• user_agent (opt-in) — which skill/plugin triggered the command

Open questions

Flag name

--user-agent collides with the existing HTTP User-Agent the CLI already sends:

apify-cli/${version} (${hash}) running on ${platform}-${arch} with ${runtime}-${runtimeVersion}${extra}, installed via ${installMethod}

Two options to resolve this:

1. Extend the existing User-Agent string — append the caller id to the metadata block so it flows to the API too.
2. Use a separate HTTP header (e.g. X-Apify-Skill) and keep the existing User-Agent untouched.

Option 2 keeps concerns separate and avoids breaking anything that parses the current format.

If we keep the --user-agent flag name, we should note it as a known trade-off to revisit if we ever need a flag that maps to the HTTP User-Agent directly.

Acceptance criteria

• Decide final flag name and HTTP-header strategy (extend vs. new header)
• Add flag + APIFY_CLI_USER_AGENT env var to all commands
• Emit value as user_agent telemetry property
• Document the flag and its intended use (skills, plugins, integrations)

References

• Parent issue: Extend CLI telemetry #1073
• Context-setting PR: feat: add execution context to telemetry events #1074