# move

> Move an item into another folder

*Changes something.*

Move an item into another folder, in its space or another one.

Expects revision, the item's observed revision, and to, the folder to land in; name
renames it as it lands. Within a space editors rearrange: editor on the item and on the
folder is enough. Across spaces the item keeps its ID, its history, its activity and its
direct grants, and comes with everything beneath it. Editor on the destination folder is
needed, by any route. In a personal space an item is its owner's — the person who made
it — wherever it sits: only its owner moves it to another space, and moving one's own
item into another person's folder leaves it one's own and charged to one's own storage.
Only an owner of an organization moves an item out of that organization, and the mover
owns what they take out. Otherwise access_denied names required owner and the space.
Moving into an organization is giving: the organization owns it from then on, and only
an owner of it takes it out again, including back to you. A move between two personal
spaces is admitted: the item stays its owner's. A move that would put a folder inside
itself is refused with cycle, one that would exceed the tree's depth with depth_limit,
one across spaces of more than 200 items with operation_limit, and one the destination
has no room for with storage_quota, node_quota or history_limit. A move that changes who
has access is refused first with a preview: access_broadens when anybody would gain,
access_narrows when somebody would only lose, each naming every subject from its role
now to its role after, owners included where the owner changes, and carrying one digest.
Relay both lists to the user, and repeat the move with acknowledge only if they say to
go ahead. Within a space only a gain is asked about. 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 move |
| `to` | text | yes | The folder to move it into |
| `name` | text | no | A new name to land under |
| `revision` | text | yes | The revision this change expects to find |
| `acknowledge` | text | no | The digest an access_broadens or access_narrows refusal carried, once the user says go ahead |
| `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 move ID --to FOLDER_ID [--name NAME] --revision REV [--acknowledge DIGEST] [--key OPERATION_KEY]
```

```sh
flie --json agent move ID --to FOLDER_ID --revision REV [--acknowledge DIGEST]
```
