alpacon edit

Edit a file on a remote server using your local editor. The file is downloaded, opened in your editor, and uploaded back to the original path when you close the editor. File transfer and permission behavior are the same as alpacon cp.

alpacon edit [USER@]SERVER:PATH [flags]

The remote path uses the format [USER@]SERVER:/path, the same as alpacon cp.

Options

  -h, --help                    help for edit
      --editor string           Editor command to run (default: ALPACON_EDITOR, VISUAL, EDITOR, then vi)
      --force                   Edit files larger than 10 MB without prompting
  -u, --username string         Specify username
  -g, --groupname string        Specify groupname
      --work-session string     Attach this edit to a work-session (overrides 'work-session use')
      --output string           Output format: table or json (default "table")

Examples

Edit a remote file:

alpacon edit my-server:/etc/nginx/nginx.conf

Edit as a specific user:

alpacon edit admin@my-server:/etc/hosts
alpacon edit -u admin my-server:/etc/hosts

Use a specific editor:

alpacon edit my-server:/etc/nginx/nginx.conf --editor "code --wait"

Edit a file larger than 10 MB without the confirmation prompt:

alpacon edit my-server:/var/log/large.txt --force

Attach the edit to a specific work session:

alpacon edit my-server:/etc/nginx/nginx.conf --work-session SESSION_ID

Editor selection

The editor is chosen in the following order:

  1. --editor flag
  2. ALPACON_EDITOR environment variable
  3. VISUAL environment variable
  4. EDITOR environment variable
  5. vi (fallback)

The --editor value is split into command and arguments without a shell, and the file path is appended as the last argument. Shell syntax such as pipes, redirections, or && will not work.

GUI editors (code, cursor, subl, and similar) return immediately after opening a window, before you save the file. Without a wait flag, your changes are not uploaded. Use the editor’s wait flag, for example --editor "code --wait". The CLI prints a warning when it detects a GUI editor without one.

Behavior

  • Existing files only: The file is downloaded before editing, so alpacon edit cannot create a new remote file.
  • Upload on change only: If you close the editor without modifying the file, the upload is skipped and the CLI prints No changes.
  • Large files: Files larger than 10 MB show a confirmation prompt before opening. Use --force to skip it. In non-interactive shells (such as scripts), the prompt is not shown and the edit is refused unless --force is set.
  • Upload failures: If your changes cannot be uploaded, the edited copy is preserved in a local temporary path, which is printed in a warning so your work is not lost.

Work session requirement

When you sign in with browser login, alpacon edit requires an active work session that includes the webftp scope. Token authentication (API token or service token) bypasses this requirement.

The session to attach is resolved from the --work-session flag, the ALPACON_WORK_SESSION environment variable, or the active session set with alpacon work-session use—in that order. When the gate denies an edit, edit exits with code 3; run with --output json to get a machine-readable diagnostic on stderr. See Gate errors for the error codes.

Last updated: