# trash

> What is in the trash, or move an item into it

*Changes something. Undoing it takes another act.*

What is in the trash, or move an item into it.

With no ID it is the trash listing, which expects nothing, changes nothing and needs no
key: it is how a trashed item's root ID is found in a later session. It lists what the
user owns that is in the trash, wherever it sits, and the trash of each organization
space at their role there. With an ID it is the change, and it expects exactly one
token: revision for a file or for an empty folder, subtree_revision for a folder with
anything beneath it, which also requires recursive. The subtree token stands over
everything retained beneath the folder, so a recursive trash cannot quietly remove a
file another agent wrote a moment ago. Only the stat tool and the link tool answer a
subtree_revision; no listing and no search carries it, because computing it reads the
whole subtree. In a personal space only an item's owner trashes it — the person who made
it, wherever it sits: the space's person holds editor on another's item and is refused
with access_denied naming required owner, and removes it instead. A recursive trash
trashes what you own beneath the folder and returns every item another person owns there
to its owner's root — a folder of theirs whole, with whatever is inside it — each
recorded as a move; the 200-item limit counts what is returned too, and a folder over it
is refused whole with operation_limit. In an organization space an editor trashes, as
before. 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 | no | The folder or file to trash; with none, the trash listing |
| `revision` | text | no | A file's or folder's own revision |
| `subtree_revision` | text | no | A folder's subtree revision, which trashing a folder expects |
| `recursive` | flag | no | Trash the folder with everything beneath it |
| `key` | text | no | A key you choose for this change, fresh each time; repeat it to settle a lost result |

## On the command line

```sh
flie agent trash [ID] [--revision REV] [--subtree-revision TOKEN] [--recursive] [--key OPERATION_KEY]
```

```sh
flie --json agent trash                                          # what is in the trash
flie --json agent trash FILE_ID --revision REV
flie --json agent trash FOLDER_ID --subtree-revision TOKEN [--recursive]  # TOKEN from stat
```
