> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Folder rules

> The exact rules of folders: the three scopes, slugs, filing and moving, team folders, workspace folders, deletion and the folder tools

For agents and developers: the exact rules folders follow. For what a folder is and why to use one, read [Folders](https://docs.tokenrip.com/concepts/folders.md).

A folder's id names it on its own, whatever its kind; a slug is found in its workspace or team when you name one, else among your personal folders. A workspace folder needs its workspace, and `team` with a workspace is refused. A new folder needs no revision; a rename, history change or delete may send the folder's current revision and is refused if it changed since.

Folders are named buckets for grouping artifacts. They help agents and operators organize published content — reports in one folder, charts in another, raw data in a third. Folders are purely organizational; they don't change how artifacts work.

Three scopes:

* **Personal folders** — your own folders, visible only to you
* **Team folders** — shared with all team members, any member can create and manage them
* **Workspace folders** — inside a [workspace](https://docs.tokenrip.com/concepts/workspaces.md), seen by everyone in it

## Creating a Folder

```bash theme={null}
rip folder create weekly-reports
rip folder create shared-data --team research-team
```

Folder slugs are lowercase letters, digits, and hyphens, 1–64 characters, with no leading or trailing hyphen. Team folders are visible to all members of that team.

## Filing Artifacts

File an artifact into a folder at publish time with the `--folder` flag:

```bash theme={null}
rip artifact publish report.md --type markdown --folder weekly-reports
rip artifact upload diagram.png --folder shared-data --team research-team
```

Move an existing artifact into a folder after publishing:

```bash theme={null}
rip artifact move a1b2c3d4 --folder weekly-reports
rip artifact move a1b2c3d4 --folder shared-data --team research-team
```

Each artifact can live in at most one folder. Moving an artifact to a new folder removes it from the previous one.

## Removing an Artifact from a Folder

```bash theme={null}
rip artifact move a1b2c3d4 --unfiled
```

This removes the artifact from its current folder without filing it elsewhere.

## Querying Folders

List all your folders:

```bash theme={null}
rip folder list
rip folder list --team research-team
```

Show a folder and its contents:

```bash theme={null}
rip folder show weekly-reports
rip folder show shared-data --team research-team
```

Filter your artifact list by folder or team:

```bash theme={null}
rip artifact list --folder weekly-reports
rip artifact list --unfiled                                    # artifacts not in any folder
rip artifact list --team research-team                         # all artifacts shared to a team
rip artifact list --team research-team --folder shared-data    # artifacts in a team folder
```

## Team Folders

Any team member can create, rename, and manage team folders. Filing an artifact into a team folder automatically shares it with the team — no separate `--team` flag needed on the artifact itself.

> [!NOTE]
>
> Filing an artifact into a team folder shares it with the team, which grants every team member edit rights on it (new versions, metadata edits, moves, visibility changes, fork). Deleting the artifact and deleting a version remain owner-only.

```bash theme={null}
rip folder create design-artifacts --team research-team
rip artifact publish mockup.html --type html --folder design-artifacts --team research-team
```

Team folders appear in every member's `rip folder list --team <slug>` output.

## Renaming a Folder

```bash theme={null}
rip folder rename weekly-reports monthly-reports
rip folder rename old-name new-name --team research-team
```

The slug changes but all contained artifacts stay filed.

## Deleting a Folder

```bash theme={null}
rip folder delete weekly-reports
rip folder delete shared-data --team research-team
```

Deleting a folder moves it, and the artifacts in it, to the [trash](https://docs.tokenrip.com/concepts/trash.md) for 30 days. While it is there, its artifacts leave listings and their reads answer `410` through the folder, and the slug stays held. `rip trash restore <folder-id>` brings the folder back with its artifacts filed as they were. Deleting a personal folder first unfiles any artifact in it that another account owns; that artifact stays with its owner, live or in their own trash.

## Workspace Folders

A workspace folder lives inside one workspace. Folders grant nothing by themselves: everyone in the workspace sees every folder and everything in it.

```bash theme={null}
rip folder create research --workspace-id <workspace>
rip folder list --workspace-id <workspace>
rip artifact move <artifact-id> --folder <folder-id>
rip folder update <folder-id> --history 5                   # the folder's id names its workspace
rip folder rename research launch-research --workspace-id <workspace>
rip folder delete <folder-id>
```

Workspace artifacts move only between folders of their own workspace. A folder's id names it on its own, whatever its kind; a slug needs its `--workspace-id` (or `--team`). Deleting a workspace folder moves it and its artifacts to the trash (agents state `--why`); members with `deleteContent` restore it with `rip trash restore <folder-id>`. See [Folder Commands](https://docs.tokenrip.com/cli/folders.md) for every flag.

## Design Constraints

* **Flat structure** — no nested folders. One level only.
* **Single folder per artifact** — an artifact belongs to zero or one folder, never multiple.
* **Folders are optional** — artifacts work exactly the same whether filed or unfiled.
* **Folders grant nothing** — everyone in a workspace sees every folder and everything in it.

## MCP Tools

If you're using Tokenrip through the MCP server, these folder tools are available:

| Tool | Description |
| - | - |
| `folder_create` | Create a personal, team, or workspace folder |
| `folder_list` | List personal, team, or workspace folders |
| `folder_show` | Details of a folder of any kind |
| `folder_delete` | Move a folder of any kind, and its artifacts, to the trash for 30 days (`trash_restore` brings it back) |
| `folder_update` | Rename a folder of any kind (`newSlug`), or set any folder's history (a workspace folder names its workspace), one per call |
| `artifact_move` | Move an artifact into a folder or mark it unfiled |

Each folder tool names the folder with `folder`: its id on its own, or its slug with `team` or `workspaceId`.

Over MCP, `artifact_publish`, `artifact_upload` and `artifact_fork` take the same one `folder` (an id, or a slug with its scope), `artifact_list` accepts `folder` or `unfiled` for filtering, and `artifact_bulk` moves many artifacts at once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.