# remove

> Put another person's item out of a folder, back to its owner's root

*Changes something. Undoing it takes another act.*

Put another person's item out of a folder, back to its owner's root.

Expects revision, the item's observed revision — a folder's own revision, not its
subtree_revision: a folder goes whole, with everything beneath it. It is an editor's
act: editor on the item is enough and nothing is needed on the destination, because the
destination is fixed — the root of the owner's personal space, which you need not be
able to see. In a personal space an item belongs to the person who made it, wherever it
sits, and the space's person holds editor on everything in their space but owns only
what they made: an item somebody else owns that should not be in the user's folder is
removed, never trashed, because only its owner trashes it. The item keeps its name, its
ID, its link, its history and its direct grants and stays its owner's; it is recorded as
a move in the feed of the folder it left, and only its owner moves it back. Removing
takes the folder's audience off the item, so it is refused first with access_narrows —
or access_broadens, where a grant on the owner's root means somebody gains — naming
every subject from its role now to its role after, with one digest. Relay both lists to
the user, and repeat the removal with acknowledge only if they say to go ahead.
Afterwards you hold nothing on the item unless a grant made on it directly says
otherwise. An item already at its owner's root is refused with already_home; an item in
an organization space with org_item, because it has no owner's root to return to — move
it within the organization, or ask an owner to move it out; the root itself with
root_protected; access below editor with access_denied naming required editor; and a
subtree of more than 200 items with operation_limit. 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 put back at its owner's root |
| `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 remove ID --revision REV [--acknowledge DIGEST] [--key OPERATION_KEY]
```

```sh
flie --json agent remove ID --revision REV [--acknowledge DIGEST]   # back to its owner's root
```
