Skip to main content

​
Folders

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’s audience needs its workspace, and team with a workspace is refused. A new folder needs no revision; a rename, audience change, share-contents 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, with an internal or shared audience of their own

​
Creating a Folder

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:
Move an existing artifact into a folder after publishing:
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

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

​
Querying Folders

List all your folders:
Show a folder and its contents:
Filter your artifact list by folder or team:

​
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.
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.
Team folders appear in every member’s rip folder list --team <slug> output.

​
Renaming a Folder

The slug changes but all contained artifacts stay filed.

​
Deleting a Folder

Deleting a folder moves it, and the artifacts in it, to the trash 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 and carries an audience, like every workspace item. Folders grant nothing by themselves: an internal folder is invisible to external members, and any shared artifacts in it appear at the workspace root for them.
share-contents shares the folder and every artifact currently in it in one atomic step; artifacts added later keep their own audience. 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 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.
  • No inheritance — a workspace folder’s audience never changes its children’s.

​
MCP Tools

If you’re using Tokenrip through the MCP server, these folder tools are available: Each tool names the folder with folder: its id on its own, or its slug with team or workspaceId. | artifact_move | Move an artifact into a folder or mark it unfiled | 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.