feat(cli): Add Analytic tracking to CLI commands

Author: blainekasten

pyproject.toml

@@ -25,6 +25,8 @@ dependencies = [
   "filelock>=3.13.1",
   "types-pyyaml>=6.0.12.20250915",
   "tomli>=2.0.0; python_version < '3.11'",
+  "py-machineid>=1.0.0",
+  "detect-agent>=0.1.0",
 ]
 
 requires-python = ">= 3.9"

src/together/lib/cli/__init__.py

@@ -14,6 +14,7 @@
 from together.lib.cli.api.beta import beta
 from together.lib.cli.api.evals import evals
 from together.lib.cli.api.files import files
+from together.lib.cli._track_cli import CliTrackingEvents, track_cli
 from together.lib.cli.api.models import models
 from together.lib.cli.api.endpoints import endpoints
 from together.lib.cli.api.fine_tuning import fine_tuning
@@ -64,7 +65,7 @@ def main(
         setup_logging()  # Must run this again here to allow the new logging configuration to take effect
 
     try:
-        ctx.obj = together.Together(
+        client = together.Together(
             api_key=api_key,
             base_url=base_url,
             timeout=timeout,
@@ -79,7 +80,7 @@ def main(
     # Instead we opt to create a dummy client and hook into any requests performed by the client. We take that moment to print the error and exit.
     except Exception as e:
         if "api_key" in str(e):
-            ctx.obj = together.Together(
+            client = together.Together(
                 api_key="0000000000000000000000000000000000000000",
                 base_url=base_url,
                 timeout=timeout,
@@ -98,11 +99,22 @@ def block_requests_for_api_key(_: httpx.Request) -> None:
                 click.secho(f"\nUsage: together --api-key <your-api-key> {invoked_command_name}", fg="yellow")
                 sys.exit(1)
 
-            ctx.obj._client.event_hooks["request"].append(block_requests_for_api_key)
+            client._client.event_hooks["request"].append(block_requests_for_api_key)
             return
 
         raise e
 
+    # Wrap the client's httpx requests to track the parameters sent on api requests
+    def track_request(request: httpx.Request) -> None:
+        track_cli(
+            CliTrackingEvents.ApiRequest,
+            {"url": str(request.url), "method": request.method, "body": request.content.decode("utf-8")},
+        )
+
+    client._client.event_hooks["request"].append(track_request)
+
+    ctx.obj = client
+
 
 main.add_command(files)
 main.add_command(fine_tuning)
@@ -112,4 +124,12 @@ def block_requests_for_api_key(_: httpx.Request) -> None:
 main.add_command(beta)
 
 if __name__ == "__main__":
-    main()
+    # When running the script, call the command with standalone_mode=False
+    # to prevent Click's default top-level exception handling from suppressing
+    # your try/except block.
+    try:
+        main(standalone_mode=False)
+    except SystemExit as e:
+        # Re-raise SystemExit if it's not a success exit (code 0)
+        if e.code != 0:
+            raise

src/together/lib/cli/_track_cli.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import os
+import json
+import time
+import uuid
+import threading
+from enum import Enum
+from typing import Any, TypeVar, Callable
+from functools import wraps
+
+import httpx
+import machineid
+from detect_agent import determine_agent
+
+from together import __version__
+from together.lib.utils import log_debug
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+SESSION_ID = int(str(uuid.uuid4().int)[0:13])
+
+
+def is_tracking_enabled() -> bool:
+    # Users can opt-out of tracking with the environment variable.
+    if os.getenv("TOGETHER_TELEMETRY_DISABLED"):
+        log_debug("Analytics tracking disabled by environment variable")
+        return False
+
+    return True
+
+
+class CliTrackingEvents(Enum):
+    CommandStarted = "cli_command_started"
+    CommandCompleted = "cli_command_completed"
+    CommandFailed = "cli_command_failed"
+    CommandUserAborted = "cli_command_user_aborted"
+    ApiRequest = "cli_command_api_request"
+
+
+def track_cli(event_name: CliTrackingEvents, args: dict[str, Any]) -> None:
+    """Track a CLI event. Non-Blocking."""
+    if is_tracking_enabled() == False:
+        return
+
+    def send_event() -> None:
+        ANALYTICS_API_ENV_VAR = os.getenv("TOGETHER_TELEMETRY_API")
+        ANALYTICS_API = (
+            ANALYTICS_API_ENV_VAR
+            if ANALYTICS_API_ENV_VAR
+            else "https://api.together.ai/together/gateway/pub/v1/httpRequest"
+        )
+
+        try:
+            agent_info = determine_agent()
+            agent_name = ""
+            if agent_info["agent"]:
+                agent_name = agent_info["agent"]["name"]
+
+            log_debug("Analytics event sending", event_name=event_name.value, args=args)
+
+            client = httpx.Client()
+            client.post(
+                ANALYTICS_API,
+                headers={"content-type": "application/json", "user-agent": f"together-cli:{__version__}"},
+                content=json.dumps(
+                    {
+                        "event_source": "cli",
+                        "event_type": event_name.value,
+                        "event_properties": {
+                            "is_ci": os.getenv("CI") is not None,
+                            "is_agent": agent_info["is_agent"],
+                            "agent_name": agent_name,
+                            **args,
+                        },
+                        "context": {
+                            "session_id": str(SESSION_ID),
+                            "runtime": {
+                                "name": "together-cli",
+                                "version": __version__,
+                            },
+                        },
+                        "identity": {
+                            "device_id": machineid.id().lower(),
+                        },
+                        "event_options": {
+                            "time": int(time.time() * 1000),
+                        },
+                    }
+                ),
+            )
+        except Exception as e:
+            log_debug("Error sending analytics event", error=e)
+            # No-op - this is not critical and we don't want to block the CLI
+            pass
+
+    threading.Thread(target=send_event).start()
+
+
+def auto_track_command(command: str) -> Callable[[F], F]:
+    """Decorator for click commands to automatically track CLI commands start/completion/failure."""
+
+    def decorator(f: F) -> F:
+        @wraps(f)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            track_cli(CliTrackingEvents.CommandStarted, {"command": command, "arguments": kwargs})
+            try:
+                f(*args, **kwargs)
+            except KeyboardInterrupt as e:
+                track_cli(
+                    CliTrackingEvents.CommandUserAborted,
+                    {"command": command, "arguments": kwargs},
+                )
+                raise e
+
+            except Exception as e:
+                track_cli(CliTrackingEvents.CommandFailed, {"command": command, "arguments": kwargs, "error": str(e)})
+                raise e
+
+            track_cli(CliTrackingEvents.CommandCompleted, {"command": command, "arguments": kwargs})
+
+        return wrapper  # type: ignore
+
+    return decorator  # type: ignore

src/together/lib/cli/api/beta/clusters/create.py

@@ -8,6 +8,7 @@
 from rich import print
 
 from together import Together
+from together.lib.cli._track_cli import auto_track_command
 from together.lib.cli.api._utils import handle_api_errors
 from together.types.beta.cluster_create_params import SharedVolume, ClusterCreateParams
 
@@ -61,6 +62,7 @@
 )
 @click.pass_context
 @handle_api_errors("Clusters")
+@auto_track_command("clusters create")
 def create(
     ctx: click.Context,
     name: str | None = None,

src/together/lib/cli/api/beta/clusters/delete.py

@@ -3,6 +3,7 @@
 import click
 
 from together import Together
+from together.lib.cli._track_cli import auto_track_command
 from together.lib.cli.api._utils import handle_api_errors
 
 
@@ -15,6 +16,7 @@
 )
 @click.pass_context
 @handle_api_errors("Clusters")
+@auto_track_command("clusters delete")
 def delete(ctx: click.Context, cluster_id: str, json: bool) -> None:
     """Delete a cluster by ID"""
     client: Together = ctx.obj

src/together/lib/cli/api/beta/clusters/get_credentials.py

@@ -10,6 +10,7 @@
 import click
 
 from together import Together, TogetherError
+from together.lib.cli._track_cli import auto_track_command
 from together.lib.cli.api._utils import handle_api_errors
 
 
@@ -39,6 +40,7 @@
 )
 @click.pass_context
 @handle_api_errors("Clusters")
+@auto_track_command("clusters get-credentials")
 def get_credentials(
     ctx: click.Context,
     cluster_id: str,

src/together/lib/cli/api/beta/clusters/list.py

@@ -3,6 +3,7 @@
 import click
 
 from together import Together
+from together.lib.cli._track_cli import auto_track_command
 
 
 @click.command()
@@ -12,6 +13,7 @@
     help="Output in JSON format",
 )
 @click.pass_context
+@auto_track_command("clusters list")
 def list(ctx: click.Context, json: bool) -> None:
     """List clusters"""
     client: Together = ctx.obj

src/together/lib/cli/api/beta/clusters/list_regions.py

@@ -5,6 +5,7 @@
 from tabulate import tabulate
 
 from together import Together
+from together.lib.cli._track_cli import auto_track_command
 from together.lib.cli.api._utils import handle_api_errors
 
 
@@ -16,6 +17,7 @@
 )
 @click.pass_context
 @handle_api_errors("Clusters")
+@auto_track_command("clusters list-regions")
 def list_regions(ctx: click.Context, json: bool) -> None:
     """List regions"""
     client: Together = ctx.obj

src/together/lib/cli/api/beta/clusters/retrieve.py

@@ -4,6 +4,7 @@
 from rich import print
 
 from together import Together
+from together.lib.cli._track_cli import auto_track_command
 from together.lib.cli.api._utils import handle_api_errors
 
 
@@ -16,6 +17,7 @@
 )
 @click.pass_context
 @handle_api_errors("Clusters")
+@auto_track_command("clusters retrieve")
 def retrieve(ctx: click.Context, cluster_id: str, json: bool) -> None:
     """Retrieve a cluster by ID"""
     client: Together = ctx.obj

src/together/lib/cli/api/beta/clusters/storage/create.py

@@ -3,6 +3,7 @@
 import click
 
 from together import Together
+from together.lib.cli._track_cli import auto_track_command
 from together.lib.cli.api._utils import handle_api_errors
 
 
@@ -31,6 +32,7 @@
     help="Output in JSON format",
 )
 @click.pass_context
+@auto_track_command("clusters storage create")
 @handle_api_errors("Clusters Storage")
 def create(ctx: click.Context, region: str, size_tib: int, volume_name: str, json: bool) -> None:
     """Create a storage volume"""