# rename

> Give an item another name

*Changes something.*

Give an item another name.

Expects revision, the item's observed revision. A folder's revision is its own name and
place, so changes beneath it do not turn it. Renaming replaces nothing: a name is a
label and may repeat among siblings. 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 |
| --- | --- | --- | --- |
| `id` | text | yes | The folder or file to rename |
| `name` | text | yes | What to call it instead |
| `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 rename ID NAME --revision REV [--key OPERATION_KEY]
```

```sh
flie --json agent rename ID "new name" --revision REV
```
