Add automatic cache cleanup on version change

thallgren · thallgren · commit 47bb6d0c6a00 · 2026-02-14T17:07:58.000+01:00
Track the CLI version in a version.json file in the cache directory.
When a version mismatch is detected, quit running daemons and clear
stale cache entries (preserving logs) to prevent issues from leftover
files after an upgrade.

Signed-off-by: Thomas Hallgren &lt;thomas@tada.se&gt;
diff --git a/CHANGELOG.yml b/CHANGELOG.yml
@@ -52,6 +52,13 @@ items:
           the need for elevated privileges when using Telepresence. Currently available for amd64 architecture only
           due to dependency constraints.
         docs: install/client
+      - type: feature
+        title: Automatic cache cleanup on version change
+        body: >-
+          Telepresence now tracks its version in a version.json file in the cache directory. When the CLI detects
+          that the major.minor version differs from the running binary, it automatically quits running daemons and
+          clears stale cache entries (preserving logs). This prevents issues caused by leftover cache files from a
+          previous version. Patch and pre-release version changes do not trigger a cache cleanup.
   - version: 2.26.2
     date: 2026-02-14
     notes:
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -195,6 +195,7 @@ Run `make generate` and commit changes to `DEPENDENCY_LICENSES.md` and `DEPENDEN
 - `pkg/agentconfig/` - Traffic-agent configuration
 - `pkg/client/k8s/` - Kubernetes client interactions
 - `pkg/routing/` - Network routing logic
+- `pkg/client/cli/cmd/` - CLI commands. One per file.
 
 ### RPC Definitions
 
diff --git a/docs/release-notes.md b/docs/release-notes.md
@@ -20,6 +20,12 @@ New Linux package installers (.deb for Debian/Ubuntu and .rpm for Fedora/RHEL) a
 A new Windows installer (.exe) is now available that installs Telepresence with the root daemon configured as a Windows service. The installer bundles WinFSP and SSHFS-Win dependencies for volume mount support, adds Telepresence to the system PATH, and optionally installs the TelepresenceDaemon service. This eliminates the need for elevated privileges when using Telepresence. Currently available for amd64 architecture only due to dependency constraints.
 </div>
 
+## <div style="display:flex;"><img src="images/feature.png" alt="feature" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">Automatic cache cleanup on version change</div></div>
+<div style="margin-left: 15px">
+
+Telepresence now tracks its version in a version.json file in the cache directory. When the CLI detects that the major.minor version differs from the running binary, it automatically quits running daemons and clears stale cache entries (preserving logs). This prevents issues caused by leftover cache files from a previous version. Patch and pre-release version changes do not trigger a cache cleanup.
+</div>
+
 ## Version 2.26.2 <span style="font-size: 16px;">(February 14)</span>
 ## <div style="display:flex;"><img src="images/bugfix.png" alt="bugfix" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">[Dial 127.0.0.1 instead of 0.0.0.0 when connecting to local daemons](https://github.com/telepresenceio/telepresence/issues/4048)</div></div>
 <div style="margin-left: 15px">
diff --git a/docs/release-notes.mdx b/docs/release-notes.mdx
@@ -26,6 +26,12 @@ New Linux package installers (.deb for Debian/Ubuntu and .rpm for Fedora/RHEL) a
 A new Windows installer (.exe) is now available that installs Telepresence with the root daemon configured as a Windows service. The installer bundles WinFSP and SSHFS-Win dependencies for volume mount support, adds Telepresence to the system PATH, and optionally installs the TelepresenceDaemon service. This eliminates the need for elevated privileges when using Telepresence. Currently available for amd64 architecture only due to dependency constraints.
   </Body>
 </Note>
+<Note>
+	<Title type="feature">Automatic cache cleanup on version change</Title>
+	<Body>
+Telepresence now tracks its version in a version.json file in the cache directory. When the CLI detects that the major.minor version differs from the running binary, it automatically quits running daemons and clears stale cache entries (preserving logs). This prevents issues caused by leftover cache files from a previous version. Patch and pre-release version changes do not trigger a cache cleanup.
+  </Body>
+</Note>
 ## Version 2.26.2 <span style={{fontSize:'16px'}}>(February 14)</span>
 <Note>
 	<Title type="bugfix" docs="https://github.com/telepresenceio/telepresence/issues/4048">Dial 127.0.0.1 instead of 0.0.0.0 when connecting to local daemons</Title>
diff --git a/pkg/client/cli/cmd/telepresence.go b/pkg/client/cli/cmd/telepresence.go
@@ -2,22 +2,30 @@ package cmd
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"io/fs"
 	"os"
+	"path/filepath"
 	"strings"
 
+	"github.com/blang/semver/v4"
 	"github.com/spf13/cobra"
 
 	"github.com/telepresenceio/clog"
 	"github.com/telepresenceio/telepresence/v2/pkg/client"
+	"github.com/telepresenceio/telepresence/v2/pkg/client/cache"
+	"github.com/telepresenceio/telepresence/v2/pkg/client/cli/connect"
 	"github.com/telepresenceio/telepresence/v2/pkg/client/cli/daemon"
 	"github.com/telepresenceio/telepresence/v2/pkg/client/cli/global"
 	"github.com/telepresenceio/telepresence/v2/pkg/client/cli/output"
 	"github.com/telepresenceio/telepresence/v2/pkg/client/docker/kubeauth"
 	"github.com/telepresenceio/telepresence/v2/pkg/client/rootd"
 	userDaemon "github.com/telepresenceio/telepresence/v2/pkg/client/userd/daemon"
 	"github.com/telepresenceio/telepresence/v2/pkg/errcat"
+	"github.com/telepresenceio/telepresence/v2/pkg/filelocation"
 	"github.com/telepresenceio/telepresence/v2/pkg/maps"
+	"github.com/telepresenceio/telepresence/v2/pkg/version"
 )
 
 // Telepresence returns the top level "telepresence" CLI command.
@@ -29,11 +37,16 @@ func Telepresence(ctx context.Context, args []string) *cobra.Command {
 		longHelp = helpMarkdown
 	}
 	rootCmd := &cobra.Command{
-		Use:               "telepresence",
-		Args:              OnlySubcommands,
-		Short:             "Connect your workstation to a Kubernetes cluster",
-		Long:              longHelp,
-		PersistentPreRunE: output.SetFormat,
+		Use:   "telepresence",
+		Args:  OnlySubcommands,
+		Short: "Connect your workstation to a Kubernetes cluster",
+		Long:  longHelp,
+		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+			if err := output.SetFormat(cmd, args); err != nil {
+				return err
+			}
+			return ensureCacheVersion(cmd, args)
+		},
 		RunE:              RunSubcommands,
 		SilenceErrors:     true, // main() will handle it after .ExecuteContext() returns
 		SilenceUsage:      true, // our FlagErrorFunc will handle it
@@ -230,3 +243,37 @@ func autocompleteContext(cmd *cobra.Command, _ []string, toComplete string) ([]s
 	}
 	return nss, cobra.ShellCompDirectiveNoFileComp
 }
+
+type versionFile struct {
+	Version semver.Version `json:"version"`
+}
+
+func ensureCacheVersion(cmd *cobra.Command, _ []string) error {
+	ctx := cmd.Context()
+	var vf versionFile
+	majorMinorMatch := false
+	if err := cache.LoadFromUserCache(ctx, &vf, "version.json"); err == nil {
+		majorMinorMatch = vf.Version.Major == version.Structured.Major && vf.Version.Minor == version.Structured.Minor
+		if majorMinorMatch {
+			return nil
+		}
+	}
+
+	// Quit all daemons (best effort, ignore errors).
+	connect.Quit(ctx)
+
+	// Clear cache except logs.
+	cacheDir := filelocation.AppUserCacheDir(ctx)
+	entries, err := os.ReadDir(cacheDir)
+	if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return err
+	}
+	for _, entry := range entries {
+		if entry.Name() == "logs" {
+			continue
+		}
+		_ = os.RemoveAll(filepath.Join(cacheDir, entry.Name()))
+	}
+
+	return cache.SaveToUserCache(ctx, &versionFile{Version: version.Structured}, "version.json", cache.Public)
+}
