fix(paths): expand ~ in user-provided file paths

When users specify paths with ~ (e.g., --out ~/Downloads/file.pdf) and
the path is quoted in the shell command, the tilde is not expanded by
the shell. This caused files to be written to a literal ~/Downloads
directory instead of the user's home directory.

Add config.ExpandPath() function that expands ~ at the beginning of
paths to the user's home directory. Apply this fix to all user-provided
file paths across:

- gmail attachment download (--out)
- drive download/export (--out)
- drive upload (localPath argument)
- auth token export (--out)
- auth credentials/import/keep (input paths)
- gmail thread attachments (--out-dir)
- gmail send/drafts (--attach)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: salmonumbrella

internal/cmd/auth.go

@@ -67,6 +67,10 @@ func (c *AuthCredentialsCmd) Run(ctx context.Context) error {
 	if inPath == "-" {
 		b, err = io.ReadAll(os.Stdin)
 	} else {
+		inPath, err = config.ExpandPath(inPath)
+		if err != nil {
+			return err
+		}
 		b, err = os.ReadFile(inPath) //nolint:gosec // user-provided path
 	}
 	if err != nil {
@@ -184,6 +188,10 @@ func (c *AuthTokensExportCmd) Run(ctx context.Context) error {
 	if outPath == "" {
 		return usage("empty outPath")
 	}
+	outPath, err := config.ExpandPath(outPath)
+	if err != nil {
+		return err
+	}
 
 	store, err := openSecretsStore()
 	if err != nil {
@@ -259,6 +267,10 @@ func (c *AuthTokensImportCmd) Run(ctx context.Context) error {
 	if inPath == "-" {
 		b, err = io.ReadAll(os.Stdin)
 	} else {
+		inPath, err = config.ExpandPath(inPath)
+		if err != nil {
+			return err
+		}
 		b, err = os.ReadFile(inPath) //nolint:gosec // user-provided path
 	}
 	if err != nil {
@@ -608,6 +620,10 @@ func (c *AuthKeepCmd) Run(ctx context.Context) error {
 	if keyPath == "" {
 		return usage("empty key path")
 	}
+	keyPath, err := config.ExpandPath(keyPath)
+	if err != nil {
+		return err
+	}
 
 	data, err := os.ReadFile(keyPath) //nolint:gosec // user-provided path
 	if err != nil {

internal/cmd/drive.go

@@ -13,6 +13,7 @@ import (
 	"google.golang.org/api/drive/v3"
 	gapi "google.golang.org/api/googleapi"
 
+	"github.com/steipete/gogcli/internal/config"
 	"github.com/steipete/gogcli/internal/googleapi"
 	"github.com/steipete/gogcli/internal/outfmt"
 	"github.com/steipete/gogcli/internal/ui"
@@ -330,6 +331,10 @@ func (c *DriveUploadCmd) Run(ctx context.Context, flags *RootFlags) error {
 	if localPath == "" {
 		return usage("empty localPath")
 	}
+	localPath, err = config.ExpandPath(localPath)
+	if err != nil {
+		return err
+	}
 
 	f, err := os.Open(localPath) //nolint:gosec // user-provided path
 	if err != nil {

internal/cmd/drive_download_helpers.go

@@ -24,6 +24,14 @@ func resolveDriveDownloadDestPath(meta *drive.File, outPathFlag string) (string,
 	}
 
 	destPath := strings.TrimSpace(outPathFlag)
+	// Expand ~ to home directory (shell doesn't expand when path is quoted).
+	if destPath != "" {
+		expanded, err := config.ExpandPath(destPath)
+		if err != nil {
+			return "", err
+		}
+		destPath = expanded
+	}
 	// Sanitize filename to prevent path traversal.
 	safeName := filepath.Base(meta.Name)
 	if safeName == "" || safeName == "." || safeName == ".." {

internal/cmd/gmail_attachment.go

@@ -71,7 +71,11 @@ func (c *GmailAttachmentCmd) Run(ctx context.Context, flags *RootFlags) error {
 		return nil
 	}
 
-	path, cached, bytes, err := downloadAttachmentToPath(ctx, svc, messageID, attachmentID, c.Output.Path, -1)
+	outPath, err := config.ExpandPath(c.Output.Path)
+	if err != nil {
+		return err
+	}
+	path, cached, bytes, err := downloadAttachmentToPath(ctx, svc, messageID, attachmentID, outPath, -1)
 	if err != nil {
 		return err
 	}

internal/cmd/gmail_drafts.go

@@ -331,7 +331,11 @@ func buildDraftMessage(ctx context.Context, svc *gmail.Service, account string,
 
 	atts := make([]mailAttachment, 0, len(input.Attach))
 	for _, p := range input.Attach {
-		atts = append(atts, mailAttachment{Path: p})
+		expanded, expandErr := config.ExpandPath(p)
+		if expandErr != nil {
+			return nil, "", expandErr
+		}
+		atts = append(atts, mailAttachment{Path: expanded})
 	}
 
 	raw, err := buildRFC822(mailOptions{

internal/cmd/gmail_send.go

@@ -10,6 +10,7 @@ import (
 
 	"google.golang.org/api/gmail/v1"
 
+	"github.com/steipete/gogcli/internal/config"
 	"github.com/steipete/gogcli/internal/outfmt"
 	"github.com/steipete/gogcli/internal/tracking"
 	"github.com/steipete/gogcli/internal/ui"
@@ -147,7 +148,11 @@ func (c *GmailSendCmd) Run(ctx context.Context, flags *RootFlags) error {
 
 	atts := make([]mailAttachment, 0, len(c.Attach))
 	for _, p := range c.Attach {
-		atts = append(atts, mailAttachment{Path: p})
+		expanded, expandErr := config.ExpandPath(p)
+		if expandErr != nil {
+			return expandErr
+		}
+		atts = append(atts, mailAttachment{Path: expanded})
 	}
 
 	var trackingCfg *tracking.Config

internal/cmd/gmail_thread.go

@@ -14,6 +14,7 @@ import (
 
 	"google.golang.org/api/gmail/v1"
 
+	"github.com/steipete/gogcli/internal/config"
 	"github.com/steipete/gogcli/internal/outfmt"
 	"github.com/steipete/gogcli/internal/ui"
 )
@@ -81,7 +82,11 @@ func (c *GmailThreadGetCmd) Run(ctx context.Context, flags *RootFlags) error {
 			// Default: current directory, not gogcli config dir.
 			attachDir = "."
 		} else {
-			attachDir = filepath.Clean(c.OutputDir.Dir)
+			expanded, err := config.ExpandPath(c.OutputDir.Dir)
+			if err != nil {
+				return err
+			}
+			attachDir = filepath.Clean(expanded)
 		}
 	}
 
@@ -292,7 +297,11 @@ func (c *GmailThreadAttachmentsCmd) Run(ctx context.Context, flags *RootFlags) e
 		if strings.TrimSpace(c.OutputDir.Dir) == "" {
 			attachDir = "."
 		} else {
-			attachDir = filepath.Clean(c.OutputDir.Dir)
+			expanded, err := config.ExpandPath(c.OutputDir.Dir)
+			if err != nil {
+				return err
+			}
+			attachDir = filepath.Clean(expanded)
 		}
 	}
 

internal/config/paths.go

@@ -153,3 +153,23 @@ func EnsureGmailWatchDir() (string, error) {
 
 	return dir, nil
 }
+
+// ExpandPath expands ~ at the beginning of a path to the user's home directory.
+// This is needed because ~ is a shell feature and is not expanded when paths
+// are quoted (e.g., --out "~/Downloads/file.pdf").
+func ExpandPath(path string) (string, error) {
+	if path == "" {
+		return "", nil
+	}
+	if path == "~" {
+		return os.UserHomeDir()
+	}
+	if strings.HasPrefix(path, "~/") {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("expand home dir: %w", err)
+		}
+		return filepath.Join(home, path[2:]), nil
+	}
+	return path, nil
+}

internal/config/paths_test.go

@@ -71,6 +71,62 @@ func TestPaths_CreateDirs(t *testing.T) {
 	}
 }
 
+func TestExpandPath(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+
+	tests := []struct {
+		name    string
+		input   string
+		want    string
+		wantErr bool
+	}{
+		{
+			name:  "empty path",
+			input: "",
+			want:  "",
+		},
+		{
+			name:  "tilde only",
+			input: "~",
+			want:  home,
+		},
+		{
+			name:  "tilde with subpath",
+			input: "~/Downloads/file.txt",
+			want:  filepath.Join(home, "Downloads/file.txt"),
+		},
+		{
+			name:  "absolute path unchanged",
+			input: "/usr/local/bin",
+			want:  "/usr/local/bin",
+		},
+		{
+			name:  "relative path unchanged",
+			input: "relative/path/file.txt",
+			want:  "relative/path/file.txt",
+		},
+		{
+			name:  "tilde in middle unchanged",
+			input: "/some/~/path",
+			want:  "/some/~/path",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ExpandPath(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("ExpandPath() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if got != tt.want {
+				t.Errorf("ExpandPath() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
 func TestKeepServiceAccountPath_SafeFilename(t *testing.T) {
 	home := t.TempDir()
 	t.Setenv("HOME", home)