# copy

> Copy a file into another folder

*Changes something.*

Copy a file into another folder.

Expects revision, the file's observed revision, and to; name gives the copy another
name. A folder is refused with folder_copy_unsupported, because a copy starts a fresh
content history: make a folder and copy the files into it. On revision_conflict nothing
was written: read the item again, work out what the change means against what is there
now, and run it again with the newly observed revision. Never fetch a fresh revision
merely to push a stale change through.

Read a revision from the stat tool, a listing, a search, the status tool, or any
change's own result.

This change takes a key you choose, fresh for this change. If its result never reaches
you, call again with the same key and the same arguments, or ask the status tool with
that key: the same key and the same input is one change, made once.

## Arguments

| Argument | Type | Required | Meaning |
| --- | --- | --- | --- |
| `file_id` | text | yes | The file to copy |
| `to` | text | yes | The folder to copy it into |
| `name` | text | no | A new name to land under |
| `revision` | text | yes | The revision this change expects to find |
| `key` | text | yes | A key you choose for this change, fresh each time; repeat it to settle a lost result |

## On the command line

```sh
flie agent copy FILE_ID --to FOLDER_ID [--name NAME] --revision REV [--key OPERATION_KEY]
```

```sh
flie --json agent copy FILE_ID --to FOLDER_ID --revision REV
```
