Implement brev copy command for file transfer (#241)

* Implement brev copy command for file transfer between local and remote workspaces

- Add new copy command in pkg/cmd/copy/copy.go following shell command patterns
- Support bidirectional copying: local->remote and remote->local
- Use scp for file transfer with workspace:path syntax parsing
- Include workspace startup logic and SSH connection handling
- Register command in SSH Commands section with aliases cp, scp
- Add --host flag for copying to/from host machine vs container

Co-Authored-By: Alec Fong <[email protected]>

* Update help text to use 'instance' instead of 'workspace'

- Change copyLong description to use 'remote instance'
- Update copyExample to use 'instance_name' in examples
- Update error messages to reference 'instance path' format
- Maintain consistency with Brev CLI terminology

Co-Authored-By: Alec Fong <[email protected]>

* Add file existence validation for local-to-remote copies

- Validate local file exists before attempting workspace connection
- Provide clear error message when file doesn't exist
- Improves UX by failing fast on missing files
- Only validates for upload operations (local-to-remote)

Co-Authored-By: Alec Fong <[email protected]>

* Add completion message with timing for copy operations

- Track transfer duration using time.Now() and time.Since()
- Display success message showing source → destination with timing
- Use terminal.Green() for colored success output following CLI patterns
- Updated runSCP function signature to accept terminal parameter
- Improves UX by confirming successful transfers with clear feedback

Co-Authored-By: Alec Fong <[email protected]>

* Fix success message formatting issues

- Use t.Vprint with fmt.Sprintf instead of t.Vprintf to fix printf formatting errors
- Ensures proper formatting of source, destination, and duration values
- Addresses GitHub comment feedback about MISSING values in output

Co-Authored-By: Alec Fong <[email protected]>

* Fix spinner not stopping before success message

- Add s.Stop() call at end of pollUntil function
- Add s.Stop() call in error path to ensure spinner is always stopped
- Ensures success message appears on new line instead of same line as spinner
- Addresses GitHub comment feedback about message formatting

Co-Authored-By: Alec Fong <[email protected]>

* Add newline before success message for proper line separation

- Add fmt.Print("\n") before success message to ensure clean line separation
- Success message now appears on completely separate line after spinner stops
- Addresses GitHub comment feedback requesting proper formatting:
  spinner line -> newline -> success message
- Follows pattern used in other commands like ollama

Co-Authored-By: Alec Fong <[email protected]>

* Add automatic directory support to brev copy command

- Detect directories using os.Stat() and IsDir()
- Add -r flag to scp when copying directories for uploads
- Always use -r flag for downloads to handle both files and directories
- Update validation messages to mention 'file or directory'
- Update help text and examples to include directory copying
- Addresses GitHub comment requesting directory support

Resolves scp error: 'local "my-dir" is not a regular file'
by automatically detecting directories and using recursive flag

Co-Authored-By: Alec Fong <[email protected]>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Alec Fong <[email protected]>

Author: devin-ai-integration[bot]

pkg/cmd/cmd.go

@@ -9,6 +9,7 @@ import (
 	"github.com/brevdev/brev-cli/pkg/cmd/clipboard"
 	"github.com/brevdev/brev-cli/pkg/cmd/configureenvvars"
 	"github.com/brevdev/brev-cli/pkg/cmd/connect"
+	"github.com/brevdev/brev-cli/pkg/cmd/copy"
 	"github.com/brevdev/brev-cli/pkg/cmd/create"
 	"github.com/brevdev/brev-cli/pkg/cmd/delete"
 	"github.com/brevdev/brev-cli/pkg/cmd/envvars"
@@ -263,6 +264,7 @@ func createCmdTree(cmd *cobra.Command, t *terminal.Terminal, loginCmdStore *stor
 	cmd.AddCommand(configureenvvars.NewCmdConfigureEnvVars(t, loginCmdStore))
 	cmd.AddCommand(importideconfig.NewCmdImportIDEConfig(t, noLoginCmdStore))
 	cmd.AddCommand(shell.NewCmdShell(t, loginCmdStore, noLoginCmdStore))
+	cmd.AddCommand(copy.NewCmdCopy(t, loginCmdStore, noLoginCmdStore))
 	cmd.AddCommand(open.NewCmdOpen(t, loginCmdStore, noLoginCmdStore))
 	cmd.AddCommand(ollama.NewCmdOllama(t, loginCmdStore))
 	cmd.AddCommand(background.NewCmdBackground(t, loginCmdStore))

pkg/cmd/copy/copy.go

@@ -0,0 +1,308 @@
+package copy
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+	"time"
+
+	"github.com/brevdev/brev-cli/pkg/cmd/cmderrors"
+	"github.com/brevdev/brev-cli/pkg/cmd/completions"
+	"github.com/brevdev/brev-cli/pkg/cmd/refresh"
+	"github.com/brevdev/brev-cli/pkg/cmd/util"
+	"github.com/brevdev/brev-cli/pkg/entity"
+	breverrors "github.com/brevdev/brev-cli/pkg/errors"
+	"github.com/brevdev/brev-cli/pkg/store"
+	"github.com/brevdev/brev-cli/pkg/terminal"
+	"github.com/brevdev/brev-cli/pkg/writeconnectionevent"
+	"github.com/briandowns/spinner"
+
+	"github.com/spf13/cobra"
+)
+
+var (
+	copyLong    = "Copy files and directories between your local machine and remote instance"
+	copyExample = "brev copy instance_name:/path/to/remote/file /path/to/local/file\nbrev copy /path/to/local/file instance_name:/path/to/remote/file\nbrev copy ./local-directory/ instance_name:/remote/path/"
+)
+
+type CopyStore interface {
+	util.GetWorkspaceByNameOrIDErrStore
+	refresh.RefreshStore
+	GetOrganizations(options *store.GetOrganizationsOptions) ([]entity.Organization, error)
+	GetWorkspaces(organizationID string, options *store.GetWorkspacesOptions) ([]entity.Workspace, error)
+	StartWorkspace(workspaceID string) (*entity.Workspace, error)
+	GetWorkspace(workspaceID string) (*entity.Workspace, error)
+	GetCurrentUserKeys() (*entity.UserKeys, error)
+}
+
+func NewCmdCopy(t *terminal.Terminal, store CopyStore, noLoginStartStore CopyStore) *cobra.Command {
+	var host bool
+	cmd := &cobra.Command{
+		Annotations:           map[string]string{"ssh": ""},
+		Use:                   "copy",
+		Aliases:               []string{"cp", "scp"},
+		DisableFlagsInUseLine: true,
+		Short:                 "copy files and directories between local and remote instance",
+		Long:                  copyLong,
+		Example:               copyExample,
+		Args:                  cmderrors.TransformToValidationError(cobra.ExactArgs(2)),
+		ValidArgsFunction:     completions.GetAllWorkspaceNameCompletionHandler(noLoginStartStore, t),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			err := runCopyCommand(t, store, args[0], args[1], host)
+			if err != nil {
+				return breverrors.WrapAndTrace(err)
+			}
+			return nil
+		},
+	}
+	cmd.Flags().BoolVarP(&host, "host", "", false, "copy to/from the host machine instead of the container")
+
+	return cmd
+}
+
+func runCopyCommand(t *terminal.Terminal, cstore CopyStore, source, dest string, host bool) error {
+	workspaceNameOrID, remotePath, localPath, isUpload, err := parseCopyArguments(source, dest)
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+
+	if isUpload {
+		err = validateLocalFile(localPath)
+		if err != nil {
+			return breverrors.WrapAndTrace(err)
+		}
+	}
+
+	workspace, err := prepareWorkspace(t, cstore, workspaceNameOrID)
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+
+	sshName, err := setupSSHConnection(t, cstore, workspace, host)
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+
+	_ = writeconnectionevent.WriteWCEOnEnv(cstore, workspace.DNS)
+
+	err = runSCP(t, sshName, localPath, remotePath, isUpload)
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+
+	return nil
+}
+
+func parseCopyArguments(source, dest string) (workspaceNameOrID, remotePath, localPath string, isUpload bool, err error) {
+	sourceWorkspace, sourcePath, err := parseWorkspacePath(source)
+	if err != nil {
+		return "", "", "", false, err
+	}
+
+	destWorkspace, destPath, err := parseWorkspacePath(dest)
+	if err != nil {
+		return "", "", "", false, err
+	}
+
+	if (sourceWorkspace == "" && destWorkspace == "") || (sourceWorkspace != "" && destWorkspace != "") {
+		return "", "", "", false, breverrors.NewValidationError("exactly one of source or destination must be an instance path (format: instance_name:/path)")
+	}
+
+	if sourceWorkspace != "" {
+		return sourceWorkspace, sourcePath, dest, false, nil
+	}
+	return destWorkspace, destPath, source, true, nil
+}
+
+func prepareWorkspace(t *terminal.Terminal, cstore CopyStore, workspaceNameOrID string) (*entity.Workspace, error) {
+	s := t.NewSpinner()
+	workspace, err := util.GetUserWorkspaceByNameOrIDErr(cstore, workspaceNameOrID)
+	if err != nil {
+		return nil, breverrors.WrapAndTrace(err)
+	}
+
+	if workspace.Status == "STOPPED" {
+		err = startWorkspaceIfStopped(t, s, cstore, workspaceNameOrID, workspace)
+		if err != nil {
+			return nil, breverrors.WrapAndTrace(err)
+		}
+	}
+
+	err = pollUntil(s, workspace.ID, "RUNNING", cstore, " waiting for instance to be ready...")
+	if err != nil {
+		return nil, breverrors.WrapAndTrace(err)
+	}
+
+	workspace, err = util.GetUserWorkspaceByNameOrIDErr(cstore, workspaceNameOrID)
+	if err != nil {
+		return nil, breverrors.WrapAndTrace(err)
+	}
+	if workspace.Status != "RUNNING" {
+		return nil, breverrors.New("Workspace is not running")
+	}
+
+	return workspace, nil
+}
+
+func setupSSHConnection(t *terminal.Terminal, cstore CopyStore, workspace *entity.Workspace, host bool) (string, error) {
+	refreshRes := refresh.RunRefreshAsync(cstore)
+
+	localIdentifier := workspace.GetLocalIdentifier()
+	if host {
+		localIdentifier = workspace.GetHostIdentifier()
+	}
+
+	sshName := string(localIdentifier)
+
+	err := refreshRes.Await()
+	if err != nil {
+		return "", breverrors.WrapAndTrace(err)
+	}
+
+	s := t.NewSpinner()
+	err = waitForSSHToBeAvailable(sshName, s)
+	if err != nil {
+		return "", breverrors.WrapAndTrace(err)
+	}
+
+	return sshName, nil
+}
+
+func validateLocalFile(localPath string) error {
+	_, err := os.Stat(localPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return breverrors.NewValidationError(fmt.Sprintf("local file or directory does not exist: %s", localPath))
+		}
+		return breverrors.WrapAndTrace(fmt.Errorf("cannot access local file or directory %s: %w", localPath, err))
+	}
+	return nil
+}
+
+func isDirectory(path string) bool {
+	info, err := os.Stat(path)
+	if err != nil {
+		return false
+	}
+	return info.IsDir()
+}
+
+func parseWorkspacePath(path string) (workspace, filePath string, err error) {
+	if !strings.Contains(path, ":") {
+		return "", path, nil
+	}
+
+	parts := strings.Split(path, ":")
+	if len(parts) != 2 {
+		return "", "", breverrors.NewValidationError("invalid instance path format, use instance_name:/path")
+	}
+
+	return parts[0], parts[1], nil
+}
+
+func runSCP(t *terminal.Terminal, sshAlias, localPath, remotePath string, isUpload bool) error {
+	var scpCmd *exec.Cmd
+	var source, dest string
+
+	startTime := time.Now()
+
+	scpArgs := []string{"scp"}
+
+	if isUpload {
+		if isDirectory(localPath) {
+			scpArgs = append(scpArgs, "-r")
+		}
+		scpArgs = append(scpArgs, localPath, fmt.Sprintf("%s:%s", sshAlias, remotePath))
+		source = localPath
+		dest = fmt.Sprintf("%s:%s", sshAlias, remotePath)
+	} else {
+		scpArgs = append(scpArgs, "-r")
+		scpArgs = append(scpArgs, fmt.Sprintf("%s:%s", sshAlias, remotePath), localPath)
+		source = fmt.Sprintf("%s:%s", sshAlias, remotePath)
+		dest = localPath
+	}
+
+	scpCmd = exec.Command(scpArgs[0], scpArgs[1:]...) //nolint:gosec //sshAlias is validated workspace identifier
+
+	output, err := scpCmd.CombinedOutput()
+	if err != nil {
+		return breverrors.WrapAndTrace(fmt.Errorf("scp failed: %s\nOutput: %s", err.Error(), string(output)))
+	}
+
+	duration := time.Since(startTime)
+	fmt.Print("\n")
+	t.Vprint(t.Green(fmt.Sprintf("✓ Successfully copied %s → %s (%v)\n", source, dest, duration.Round(time.Millisecond))))
+
+	return nil
+}
+
+func waitForSSHToBeAvailable(sshAlias string, s *spinner.Spinner) error {
+	counter := 0
+	s.Suffix = " waiting for SSH connection to be available"
+	s.Start()
+	for {
+		cmd := exec.Command("ssh", "-o", "ConnectTimeout=10", sshAlias, "echo", " ")
+		out, err := cmd.CombinedOutput()
+		if err == nil {
+			s.Stop()
+			return nil
+		}
+
+		outputStr := string(out)
+		stdErr := strings.Split(outputStr, "\n")[1]
+
+		if counter == 40 || !store.SatisfactorySSHErrMessage(stdErr) {
+			return breverrors.WrapAndTrace(errors.New("\n" + stdErr))
+		}
+
+		counter++
+		time.Sleep(1 * time.Second)
+	}
+}
+
+func startWorkspaceIfStopped(t *terminal.Terminal, s *spinner.Spinner, tstore CopyStore, wsIDOrName string, workspace *entity.Workspace) error {
+	activeOrg, err := tstore.GetActiveOrganizationOrDefault()
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+	workspaces, err := tstore.GetWorkspaceByNameOrID(activeOrg.ID, wsIDOrName)
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+	startedWorkspace, err := tstore.StartWorkspace(workspaces[0].ID)
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+	t.Vprintf(t.Yellow("Instance %s is starting. \n\n", startedWorkspace.Name))
+	err = pollUntil(s, workspace.ID, entity.Running, tstore, " hang tight 🤙")
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+	workspace, err = util.GetUserWorkspaceByNameOrIDErr(tstore, wsIDOrName)
+	if err != nil {
+		return breverrors.WrapAndTrace(err)
+	}
+	return nil
+}
+
+func pollUntil(s *spinner.Spinner, wsid string, state string, copyStore CopyStore, waitMsg string) error {
+	isReady := false
+	s.Suffix = waitMsg
+	s.Start()
+	for !isReady {
+		time.Sleep(5 * time.Second)
+		ws, err := copyStore.GetWorkspace(wsid)
+		if err != nil {
+			s.Stop()
+			return breverrors.WrapAndTrace(err)
+		}
+		s.Suffix = waitMsg
+		if ws.Status == state {
+			isReady = true
+		}
+	}
+	s.Stop()
+	return nil
+}