feat(cli): add PostHog telemetry tracking

Author: hussufo

docs/references/steel-cli.md

@@ -73,16 +73,29 @@ For generated flags and argument schemas, use [../cli-reference.md](../cli-refer
 
 - Config directory: `~/.config/steel`
 - Main config: `~/.config/steel/config.json`
+- Telemetry state: `~/.config/steel/telemetry.json`
 - Browser session state: `~/.config/steel/browser-session-state.json`
 - Profile metadata: `~/.config/steel/profiles/<name>.json`
 
+Telemetry can be disabled persistently in `config.json` with:
+
+```json
+{
+  "telemetry": {
+    "disabled": true
+  }
+}
+```
+
 ## Environment Variables (Common)
 
 - `STEEL_API_KEY`: cloud auth for session API and browser runtime.
 - `STEEL_API_URL`: cloud API endpoint override.
 - `STEEL_BROWSER_API_URL`: canonical self-hosted local endpoint override.
 - `STEEL_LOCAL_API_URL`: backward-compatible self-hosted alias.
 - `STEEL_CONFIG_DIR`: override config directory root.
+- `STEEL_TELEMETRY_HOST`: override the PostHog ingest host.
+- `STEEL_TELEMETRY_DISABLED`: force telemetry off.
 - `STEEL_PROFILE`: default profile name for browser sessions.
 
 ## Key References

src/commands/browser/action.rs

@@ -161,6 +161,50 @@ pub enum ActionCommand {
     Close,
 }
 
+impl ActionCommand {
+    pub const fn telemetry_name(&self) -> &'static str {
+        match self {
+            Self::Navigate(_) => "navigate",
+            Self::Back => "back",
+            Self::Forward => "forward",
+            Self::Reload => "reload",
+            Self::Click(_) => "click",
+            Self::DblClick(_) => "dblclick",
+            Self::Fill(_) => "fill",
+            Self::Type(_) => "type",
+            Self::Press(_) => "press",
+            Self::Hover(_) => "hover",
+            Self::Focus(_) => "focus",
+            Self::Check(_) => "check",
+            Self::Uncheck(_) => "uncheck",
+            Self::Select(_) => "select",
+            Self::Clear(_) => "clear",
+            Self::SelectAll(_) => "selectall",
+            Self::Scroll(_) => "scroll",
+            Self::ScrollIntoView(_) => "scrollintoview",
+            Self::SetValue(_) => "setvalue",
+            Self::Snapshot(_) => "snapshot",
+            Self::Screenshot(_) => "screenshot",
+            Self::Eval(_) => "eval",
+            Self::Find(_) => "find",
+            Self::Content => "content",
+            Self::Get { .. } => "get",
+            Self::Is { .. } => "is",
+            Self::Wait(_) => "wait",
+            Self::Tab { .. } => "tab",
+            Self::Cookies { .. } => "cookies",
+            Self::Storage { .. } => "storage",
+            Self::Drag(_) => "drag",
+            Self::Upload(_) => "upload",
+            Self::Highlight(_) => "highlight",
+            Self::Set { .. } => "set",
+            Self::BringToFront => "bringtofront",
+            Self::Diff { .. } => "diff",
+            Self::Close => "close",
+        }
+    }
+}
+
 // ── Get subcommands ─────────────────────────────────────────────────
 
 #[derive(Subcommand)]

src/commands/browser/captcha.rs

@@ -16,6 +16,15 @@ pub enum Command {
     Status(StatusArgs),
 }
 
+impl Command {
+    pub const fn telemetry_name(&self) -> &'static str {
+        match self {
+            Self::Solve(_) => "solve",
+            Self::Status(_) => "status",
+        }
+    }
+}
+
 #[derive(Parser)]
 pub struct SolveArgs {
     /// Explicit session ID (overrides --session name lookup)

src/commands/browser/mod.rs

@@ -46,6 +46,20 @@ pub enum Command {
     Action(action::ActionCommand),
 }
 
+impl Command {
+    pub fn telemetry_name(&self) -> String {
+        match self {
+            Self::Start(_) => "start".to_string(),
+            Self::Stop(_) => "stop".to_string(),
+            Self::Sessions(_) => "sessions".to_string(),
+            Self::Live(_) => "live".to_string(),
+            Self::Captcha { command } => format!("captcha.{}", command.telemetry_name()),
+            Self::Batch(_) => "batch".to_string(),
+            Self::Action(action) => action.telemetry_name().to_string(),
+        }
+    }
+}
+
 pub async fn run(args: BrowserArgs) -> anyhow::Result<()> {
     let session = args.session;
     if let Some(ref name) = session

src/commands/browser/start.rs

@@ -73,6 +73,8 @@ pub async fn run(args: Args, session: Option<&str>) -> anyhow::Result<()> {
     }
 
     let persist_profile = args.profile.is_some() && args.update_profile;
+    let proxy_enabled = args.proxy.is_some();
+    let namespace_set = args.namespace.is_some();
 
     // If a daemon is already running for this session name, stop it first.
     // `start` always creates a fresh session — use `steel browser sessions`
@@ -122,6 +124,19 @@ pub async fn run(args: Args, session: Option<&str>) -> anyhow::Result<()> {
         )?;
     }
 
+    let mut properties = serde_json::Map::new();
+    properties.insert("stealth".into(), json!(args.stealth));
+    properties.insert("proxy_enabled".into(), json!(proxy_enabled));
+    properties.insert("has_profile".into(), json!(args.profile.is_some()));
+    properties.insert("persist_profile".into(), json!(persist_profile));
+    properties.insert("credentials".into(), json!(args.credentials));
+    properties.insert("namespace_set".into(), json!(namespace_set));
+    properties.insert(
+        "session_timeout_set".into(),
+        json!(args.session_timeout.is_some()),
+    );
+    crate::telemetry::track_event("browser_session_started", properties);
+
     display_session_info(&info);
 
     Ok(())

src/commands/browser/stop.rs

@@ -16,6 +16,7 @@ pub async fn run(args: Args, session: Option<&str>) -> anyhow::Result<()> {
         anyhow::bail!("Cannot combine `--all` with `--session`.");
     }
 
+    let stopped_count;
     if args.all {
         let names = process::list_daemon_names();
         if names.is_empty() {
@@ -30,6 +31,7 @@ pub async fn run(args: Args, session: Option<&str>) -> anyhow::Result<()> {
         for name in &names {
             let _ = process::stop_daemon(name).await;
         }
+        stopped_count = names.len() as u64;
 
         if output::is_json() {
             output::success_data(json!({ "stoppedSessions": names }));
@@ -39,6 +41,7 @@ pub async fn run(args: Args, session: Option<&str>) -> anyhow::Result<()> {
     } else {
         let session_name = session.unwrap_or("default");
         process::stop_daemon(session_name).await?;
+        stopped_count = 1;
 
         if output::is_json() {
             output::success_data(json!({ "stoppedSessions": [session_name] }));
@@ -47,5 +50,10 @@ pub async fn run(args: Args, session: Option<&str>) -> anyhow::Result<()> {
         }
     }
 
+    let mut properties = serde_json::Map::new();
+    properties.insert("all".into(), json!(args.all));
+    properties.insert("stopped_count".into(), json!(stopped_count));
+    crate::telemetry::track_event("browser_session_stopped", properties);
+
     Ok(())
 }

src/commands/config.rs

@@ -32,5 +32,9 @@ pub async fn run(_args: Args) -> anyhow::Result<()> {
         println!("browser.apiUrl: {url}");
     }
 
+    if let Some(ref cfg) = config {
+        println!("telemetry.disabled: {}", cfg.telemetry_disabled());
+    }
+
     Ok(())
 }

src/commands/credentials.rs

@@ -19,6 +19,17 @@ pub enum Command {
     Delete(DeleteArgs),
 }
 
+impl Command {
+    pub const fn telemetry_name(&self) -> &'static str {
+        match self {
+            Self::List(_) => "list",
+            Self::Create(_) => "create",
+            Self::Update(_) => "update",
+            Self::Delete(_) => "delete",
+        }
+    }
+}
+
 #[derive(Parser)]
 pub struct ListArgs {
     /// Filter by namespace

src/commands/dev.rs

@@ -17,6 +17,16 @@ pub enum Command {
     Stop(StopArgs),
 }
 
+impl Command {
+    pub const fn telemetry_name(&self) -> &'static str {
+        match self {
+            Self::Install(_) => "install",
+            Self::Start(_) => "start",
+            Self::Stop(_) => "stop",
+        }
+    }
+}
+
 #[derive(Parser)]
 pub struct InstallArgs {
     /// Git repository URL for local Steel Browser runtime

src/commands/login.rs

@@ -27,6 +27,8 @@ pub async fn run(_args: Args) -> anyhow::Result<()> {
 
     save_api_key(&api_key, &name)?;
 
+    crate::telemetry::track_event("login_completed", serde_json::Map::new());
+
     status!("Authentication successful! Your API key has been saved.");
 
     Ok(())