---
title: "alpacon edit"
description: "Edit remote files with your local editor. Download a file, edit it locally, and upload changes back to the server automatically when the editor exits."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# alpacon edit

Edit a remote file with your local editor.

## Usage

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

## Key facts

- The remote path uses `[USER@]SERVER:/path`.
- Closing the editor uploads the changed file to its original path.
- File transfer permissions follow `alpacon cp`.

## Flags

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

## Examples

Edit a remote file

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

Edit as a specific user

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

Use a specific editor

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

Edit a file larger than 10 MB without the confirmation prompt

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

Attach the edit to a specific work session

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

## Details

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`](/reference/cli/cp/).

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

## 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](/reference/cli/work-session/) that includes the `webftp` scope. Service-token authentication bypasses this requirement. The token still needs a server ACL entry allowing the target server and a file ACL entry allowing the path: `upload` to send a file, `download` to fetch it, and both (or `*`) for `edit`.

New personal API tokens cannot hold command-execution or file-transfer scopes. Existing tokens with those scopes keep working without a work session. Use a [service token](/use/iam/applications/service-tokens/) for automation and CI.

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`](/reference/cli/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](/reference/cli/work-session/#gate-errors) for the error codes.

Source: https://docs.alpacax.com/reference/cli/edit/
