✨ feat: Add anonymous PostHog telemetry to mb CLI

.dagger/main.go

@@ -92,6 +92,10 @@ func (m *Masterblaster) BuildRelease(
 
 	// Git commit SHA of build
 	commit string,
+
+	// PostHog telemetry public key
+	// +optional
+	postHogPublicKey string,
 ) *dagger.Directory {
 	buildtime := time.Now()
 
@@ -103,6 +107,10 @@ func (m *Masterblaster) BuildRelease(
 		fmt.Sprintf("-X 'github.com/papercomputeco/masterblaster/pkg/utils.Buildtime=%s'", buildtime),
 	}
 
+	if postHogPublicKey != "" {
+		ldflags = append(ldflags, fmt.Sprintf("-X 'github.com/papercomputeco/masterblaster/pkg/telemetry.PostHogAPIKey=%s'", postHogPublicKey))
+	}
+
 	dir := m.Build(ctx, strings.Join(ldflags, " "))
 	return dag.Checksumer().Checksum(dir)
 }

.dagger/release.go

@@ -29,8 +29,12 @@ func (m *Masterblaster) ReleaseLatest(
 
 	// Bucket secret access key
 	secretAccessKey *dagger.Secret,
+
+	// PostHog telemetry public key
+	// +optional
+	postHogPublicKey string,
 ) (*dagger.Directory, error) {
-	artifacts := m.BuildRelease(ctx, version, commit)
+	artifacts := m.BuildRelease(ctx, version, commit, postHogPublicKey)
 
 	uploader := dag.Bucketuploader(endpoint, bucket, accessKeyId, secretAccessKey)
 	if err := uploader.UploadLatest(ctx, artifacts, version); err != nil {
@@ -59,8 +63,12 @@ func (m *Masterblaster) ReleaseNightly(
 
 	// Bucket secret access key
 	secretAccessKey *dagger.Secret,
+
+	// PostHog telemetry public key
+	// +optional
+	postHogPublicKey string,
 ) (*dagger.Directory, error) {
-	artifacts := m.BuildRelease(ctx, "nightly", commit)
+	artifacts := m.BuildRelease(ctx, "nightly", commit, postHogPublicKey)
 
 	uploader := dag.Bucketuploader(endpoint, bucket, accessKeyId, secretAccessKey)
 	if err := uploader.UploadNightly(ctx, artifacts); err != nil {

.github/workflows/nightly.yaml

@@ -79,6 +79,7 @@ jobs:
           dagger call \
             release-nightly \
               --commit="${{ github.sha }}" \
+              --post-hog-public-key="${{ secrets.POSTHOG_API_KEY }}" \
               --endpoint=env://BUCKET_ENDPOINT \
               --bucket=env://BUCKET_NAME \
               --access-key-id=env://BUCKET_ACCESS_KEY_ID \
@@ -114,7 +115,7 @@ jobs:
           go-version-file: go.mod
 
       - name: Build and codesign darwin/arm64 binary
-        run: make apple-build VERSION=nightly COMMIT="${{ github.sha }}"
+        run: make apple-build VERSION=nightly COMMIT="${{ github.sha }}" POSTHOG_API_KEY="${{ secrets.POSTHOG_API_KEY }}"
 
       - name: Generate checksum
         run: shasum -a 256 build/darwin/arm64/mb > build/darwin/arm64/mb.sha256

.github/workflows/release.yaml

@@ -29,6 +29,7 @@ jobs:
             release-latest \
               --version="${{ github.event.release.tag_name }}" \
               --commit="${{ github.sha }}" \
+              --post-hog-public-key="${{ secrets.POSTHOG_API_KEY }}" \
               --endpoint=env://BUCKET_ENDPOINT \
               --bucket=env://BUCKET_NAME \
               --access-key-id=env://BUCKET_ACCESS_KEY_ID \
@@ -65,7 +66,7 @@ jobs:
           go-version-file: go.mod
 
       - name: Build and codesign darwin/arm64 binary
-        run: make apple-build
+        run: make apple-build POSTHOG_API_KEY="${{ secrets.POSTHOG_API_KEY }}"
 
       - name: Generate checksum
         run: shasum -a 256 build/darwin/arm64/mb > build/darwin/arm64/mb.sha256

cmd/down/down.go

@@ -8,6 +8,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/papercomputeco/masterblaster/pkg/daemon/client"
+	"github.com/papercomputeco/masterblaster/pkg/telemetry"
 	"github.com/papercomputeco/masterblaster/pkg/ui"
 )
 
@@ -35,12 +36,14 @@ func NewDownCmd(configDirFn func() string) *cobra.Command {
 		Short: downShortDesc,
 		Long:  downLongDesc,
 		Args:  cobra.MaximumNArgs(1),
-		RunE: func(_ *cobra.Command, args []string) error {
+		RunE: func(cmd *cobra.Command, args []string) error {
 			name := ""
 			if len(args) > 0 {
 				name = args[0]
 			}
-			return runDown(configDirFn(), name, force)
+			telem := telemetry.FromContext(cmd.Context())
+			telem.CaptureCommandRun(cmd.CommandPath())
+			return runDown(configDirFn(), name, force, telem)
 		},
 	}
 
@@ -49,14 +52,18 @@ func NewDownCmd(configDirFn func() string) *cobra.Command {
 	return cmd
 }
 
-func runDown(baseDir, name string, force bool) error {
+func runDown(baseDir, name string, force bool, telem *telemetry.PosthogClient) error {
 	if err := client.EnsureDaemon(baseDir); err != nil {
 		return err
 	}
 
 	c := client.New(baseDir)
-	return ui.Step(os.Stderr, "Stopping sandbox...", func() error {
+	err := ui.Step(os.Stderr, "Stopping sandbox...", func() error {
 		_, err := c.Down(name, force)
 		return err
 	})
+
+	telem.CaptureDown(err == nil)
+
+	return err
 }

cmd/pull/pull.go

@@ -9,6 +9,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/papercomputeco/masterblaster/pkg/mixtapes"
+	"github.com/papercomputeco/masterblaster/pkg/telemetry"
 	"github.com/papercomputeco/masterblaster/pkg/ui"
 )
 
@@ -40,14 +41,20 @@ func NewPullCmd(configDirFn func() string) *cobra.Command {
 		Short: pullShortDesc,
 		Long:  pullLongDesc,
 		Args:  cobra.ExactArgs(1),
-		RunE: func(_ *cobra.Command, args []string) error {
-			return runPull(configDirFn(), args[0])
+		RunE: func(cmd *cobra.Command, args []string) error {
+			telem := telemetry.FromContext(cmd.Context())
+			telem.CaptureCommandRun(cmd.CommandPath())
+			return runPull(configDirFn(), args[0], telem)
 		},
 	}
 }
 
-func runPull(baseDir, rawRef string) error {
-	return ui.Step(os.Stderr, fmt.Sprintf("Pulling mixtape %q...", rawRef), func() error {
+func runPull(baseDir, rawRef string, telem *telemetry.PosthogClient) error {
+	err := ui.Step(os.Stderr, fmt.Sprintf("Pulling mixtape %q...", rawRef), func() error {
 		return mixtapes.Pull(baseDir, rawRef)
 	})
+
+	telem.CapturePull(rawRef, err == nil)
+
+	return err
 }

cmd/ssh/ssh.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/papercomputeco/masterblaster/pkg/daemon/client"
 	"github.com/papercomputeco/masterblaster/pkg/ssh"
+	"github.com/papercomputeco/masterblaster/pkg/telemetry"
 	"github.com/papercomputeco/masterblaster/pkg/ui"
 )
 
@@ -35,12 +36,14 @@ func NewSSHCmd(configDirFn func() string, verboseFn func() bool) *cobra.Command
 		Short: sshShortDesc,
 		Long:  sshLongDesc,
 		Args:  cobra.MaximumNArgs(1),
-		RunE: func(_ *cobra.Command, args []string) error {
+		RunE: func(cmd *cobra.Command, args []string) error {
 			name := ""
 			if len(args) > 0 {
 				name = args[0]
 			}
-			return runSSH(configDirFn(), name, user, verboseFn())
+			telem := telemetry.FromContext(cmd.Context())
+			telem.CaptureCommandRun(cmd.CommandPath())
+			return runSSH(configDirFn(), name, user, verboseFn(), telem)
 		},
 	}
 
@@ -49,7 +52,7 @@ func NewSSHCmd(configDirFn func() string, verboseFn func() bool) *cobra.Command
 	return cmd
 }
 
-func runSSH(baseDir, name, user string, verbose bool) error {
+func runSSH(baseDir, name, user string, verbose bool, telem *telemetry.PosthogClient) error {
 	if err := client.EnsureDaemon(baseDir); err != nil {
 		return err
 	}
@@ -73,5 +76,10 @@ func runSSH(baseDir, name, user string, verbose bool) error {
 		ui.Info("Connecting to %s@127.0.0.1:%d", user, sb.SSHPort)
 	}
 
+	telem.CaptureSSH()
+	// ExecSSH replaces the process via syscall.Exec, so PersistentPostRunE
+	// never runs. Flush telemetry now to ensure events reach PostHog.
+	telem.Done()
+
 	return ssh.ExecSSH(user, "127.0.0.1", sb.SSHPort, sb.SSHKeyPath)
 }

cmd/up/up.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/papercomputeco/masterblaster/pkg/daemon"
 	"github.com/papercomputeco/masterblaster/pkg/daemon/client"
+	"github.com/papercomputeco/masterblaster/pkg/telemetry"
 	"github.com/papercomputeco/masterblaster/pkg/ui"
 )
 
@@ -37,8 +38,10 @@ func NewUpCmd(configDirFn func() string) *cobra.Command {
 		Short: upShortDesc,
 		Long:  upLongDesc,
 		Args:  cobra.NoArgs,
-		RunE: func(_ *cobra.Command, _ []string) error {
-			return runUp(configDirFn(), cfgPath)
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			telem := telemetry.FromContext(cmd.Context())
+			telem.CaptureCommandRun(cmd.CommandPath())
+			return runUp(configDirFn(), cfgPath, telem)
 		},
 	}
 
@@ -47,7 +50,7 @@ func NewUpCmd(configDirFn func() string) *cobra.Command {
 	return cmd
 }
 
-func runUp(baseDir, cfgPath string) error {
+func runUp(baseDir, cfgPath string, telem *telemetry.PosthogClient) error {
 	// Resolve config path
 	if cfgPath == "" {
 		cwd, err := os.Getwd()
@@ -78,9 +81,16 @@ func runUp(baseDir, cfgPath string) error {
 		resp, stepErr = c.Up("", cfgPath)
 		return stepErr
 	}); err != nil {
+		telem.CaptureUp("", false)
 		return err
 	}
 
+	mixtapeName := ""
+	if len(resp.Sandboxes) > 0 {
+		mixtapeName = resp.Sandboxes[0].Mixtape
+	}
+	telem.CaptureUp(mixtapeName, true)
+
 	if len(resp.Sandboxes) > 0 {
 		sb := resp.Sandboxes[0]
 		fmt.Fprintln(os.Stderr)

go.mod

@@ -8,9 +8,11 @@ require (
 	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/charmbracelet/x/term v0.2.2
 	github.com/google/go-containerregistry v0.21.0
+	github.com/google/uuid v1.6.0
 	github.com/klauspost/compress v1.18.4
 	github.com/onsi/ginkgo/v2 v2.28.1
 	github.com/onsi/gomega v1.39.1
+	github.com/posthog/posthog-go v1.10.0
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
 	golang.org/x/crypto v0.48.0
@@ -32,8 +34,10 @@ require (
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
+	github.com/goccy/go-json v0.10.5 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83 // indirect
+	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect

go.sum

@@ -46,6 +46,8 @@ github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1v
 github.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8=
 github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
 github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
+github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/goccy/go-yaml v1.18.0 h1:8W7wMFS12Pcas7KU+VVkaiCng+kG8QiFeFwzFb+rwuw=
 github.com/goccy/go-yaml v1.18.0/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
@@ -54,6 +56,10 @@ github.com/google/go-containerregistry v0.21.0 h1:ocqxUOczFwAZQBMNE7kuzfqvDe0VWo
 github.com/google/go-containerregistry v0.21.0/go.mod h1:ctO5aCaewH4AK1AumSF5DPW+0+R+d2FmylMJdp5G7p0=
 github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83 h1:z2ogiKUYzX5Is6zr/vP9vJGqPwcdqsWjOt+V8J7+bTc=
 github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/joshdk/go-junit v1.0.0 h1:S86cUKIdwBHWwA6xCmFlf3RTLfVXYQfvanM5Uh+K6GE=
@@ -92,6 +98,8 @@ github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/posthog/posthog-go v1.10.0 h1:wfoy7Jfb4LigCoHYyMZoiJmmEoCLOkSaYfDxM/NtCqY=
+github.com/posthog/posthog-go v1.10.0/go.mod h1:wB3/9Q7d9gGb1P/yf/Wri9VBlbP8oA8z++prRzL5OcY=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=

main.go

@@ -4,8 +4,10 @@ import (
 	"os"
 
 	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
 
 	"github.com/papercomputeco/masterblaster/pkg/ui"
+	"github.com/papercomputeco/masterblaster/pkg/utils"
 
 	destroycmder "github.com/papercomputeco/masterblaster/cmd/destroy"
 	downcmder "github.com/papercomputeco/masterblaster/cmd/down"
@@ -20,6 +22,7 @@ import (
 	versioncmder "github.com/papercomputeco/masterblaster/cmd/version"
 	vmhostcmder "github.com/papercomputeco/masterblaster/cmd/vmhost"
 	"github.com/papercomputeco/masterblaster/pkg/mbconfig"
+	"github.com/papercomputeco/masterblaster/pkg/telemetry"
 )
 
 const rootLongDesc string = `Masterblaster (mb) is an AI agent sandbox management, build, and
@@ -38,13 +41,13 @@ func NewMbCmd() *cobra.Command {
 		Long:          rootLongDesc,
 		SilenceUsage:  true,
 		SilenceErrors: true,
-		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
-			return mbconfig.Init(cmd)
-		},
+		PersistentPreRunE:  initTelemetry,
+		PersistentPostRunE: closeTelemetry,
 	}
 
 	cmd.PersistentFlags().String("config-dir", "", "Config directory (default: $XDG_CONFIG_HOME/mb)")
 	cmd.PersistentFlags().BoolP("verbose", "v", false, "Enable verbose output")
+	cmd.PersistentFlags().Bool("disable-telemetry", false, "Disable anonymous telemetry")
 
 	cmd.AddCommand(servecmder.NewServeCmd(mbconfig.ConfigDir))
 	cmd.AddCommand(initcmder.NewInitCmd())
@@ -62,6 +65,38 @@ func NewMbCmd() *cobra.Command {
 	return cmd
 }
 
+// initTelemetry initializes anonymous telemetry and stores the client in the
+// command context. Telemetry is silently skipped when disabled via config/flag/env
+// or CI detection -- errors during init never block command execution.
+func initTelemetry(cmd *cobra.Command, _ []string) error {
+	// Init config first so Viper binds the disable-telemetry flag/env/config.
+	if err := mbconfig.Init(cmd); err != nil {
+		return err
+	}
+
+	// Viper handles flag < env < config precedence for disable-telemetry.
+	if viper.GetBool("disable-telemetry") {
+		return nil
+	}
+
+	if telemetry.IsCI() {
+		return nil
+	}
+
+	telem := telemetry.NewPosthogClient(true, utils.Version)
+	telem.CaptureInstall()
+
+	cmd.SetContext(telemetry.WithContext(cmd.Context(), telem))
+
+	return nil
+}
+
+// closeTelemetry flushes pending events and shuts down the PostHog client.
+func closeTelemetry(cmd *cobra.Command, _ []string) error {
+	telemetry.FromContext(cmd.Context()).Done()
+	return nil
+}
+
 func main() {
 	cmd := NewMbCmd()