Folder Commands

Folders group artifacts into named buckets for organization. See Folders for the full concept guide. Every command that names a folder takes <folder>: its id, which names one folder of any kind (personal, team or workspace) on its own, or its slug, looked up in --workspace-id when given, else in --team, else among your personal folders.

`rip folder create`

Create a new folder: personal, a team’s (--team), or a workspace’s (--workspace-id). Workspace creation needs no expected revision. --audience requires --workspace-id (refused locally as INVALID_SCOPE before any request), and a workspace folder needs --why; --team with --workspace-id is refused locally as WORKSPACE_AUTHORITY (the server refuses the same pair as INVALID_FIELD).

rip folder create <slug> [options]

Argument	Description
`<slug>`	Unique folder identifier (lowercase letters, digits, and hyphens; 1–64 chars; no leading or trailing hyphen)

Option	Description
`--team <team-slug>`	Create the folder under a team instead of personally
`--workspace-id <workspace>`	Create inside a workspace instead (not with `--team`)
`--audience <audience>`	Workspace folders only: `internal` or `shared` (defaults to `internal` for internal members, `shared` for external editors)
`--why <text>`	One sentence on what the person is trying to accomplish, in their terms (not a description of this edit). Required for workspace items; `TOKENRIP_WHY` stands in for it

rip folder create weekly-reports
rip folder create shared-data --team research-team

{
  "ok": true,
  "data": {
    "id": "...",
    "slug": "weekly-reports",
    "team_id": null,
    "artifact_count": 0,
    "created_at": "2026-04-21T..."
  }
}

`rip folder list`

List all folders you have access to.

rip folder list [options]

Option	Description
`--team <team-slug>`	List only folders belonging to a team
`--workspace-id <workspace>`	List the folders you may see in a workspace (internal folders are hidden from external members)

rip folder list
rip folder list --team research-team

{
  "ok": true,
  "data": [
    {
      "id": "...",
      "slug": "weekly-reports",
      "team_id": null,
      "artifact_count": 5,
      "created_at": "2026-04-21T..."
    },
    {
      "id": "...",
      "slug": "shared-data",
      "team_id": "...",
      "artifact_count": 12,
      "created_at": "2026-04-20T..."
    }
  ]
}

`rip folder show`

Show a folder’s details. artifact_count counts a personal or team folder’s live artifacts; it is null for a workspace folder.

rip folder show <folder> [options]

Option	Description
`--team <team-slug>`	The team a folder slug belongs to
`--workspace-id <workspace>`	The workspace a folder slug is in

rip folder show weekly-reports
rip folder show shared-data --team research-team
rip folder show 7c9e6679-7425-40de-944b-e07fc1f90ae7

{
  "ok": true,
  "data": {
    "id": "...",
    "slug": "weekly-reports",
    "team_id": null,
    "artifact_count": 5,
    "artifacts": [
      { "id": "a1b2c3d4-...", "title": "Week 16 Report", "type": "markdown" },
      { "id": "e5f6a7b8-...", "title": "Week 15 Report", "type": "markdown" }
    ],
    "created_at": "2026-04-21T..."
  }
}

`rip folder rename`

Give a folder of any kind a new slug (PATCH /v0/folders/{folder} with newSlug).

rip folder rename <folder> <new-slug> [options]

Option	Description
`--team <team-slug>`	The team a folder slug belongs to
`--workspace-id <workspace>`	The workspace a folder slug is in
`--expected-workspace-revision <n>`	Optional, for workspace folders: the folder’s current `workspaceRevision` (a stale value is `CONFLICT`)
`--why <text>`	One sentence on what the person is trying to accomplish, in their terms (not a description of this edit). Required for workspace items; `TOKENRIP_WHY` stands in for it

rip folder rename weekly-reports monthly-reports
rip folder rename old-name new-name --team research-team
rip folder rename drafts launch-drafts --workspace-id <workspace> --why "Name the drafts for the launch"

{
  "ok": true,
  "data": {
    "id": "...",
    "slug": "monthly-reports",
    "team_id": null,
    "artifact_count": 5,
    "created_at": "2026-04-21T..."
  }
}

`rip folder delete`

Move a folder and the artifacts in it to the trash, restorable for 30 days.

rip folder delete <folder> [options]

Option	Description
`--team <team-slug>`	The team a folder slug belongs to
`--workspace-id <workspace>`	The workspace a folder slug is in
`--expected-workspace-revision <n>`	Optional, for workspace folders: the folder’s current `workspaceRevision` (a stale value is `CONFLICT`)
`--why <text>`	One sentence on what the person is trying to accomplish, in their terms (not a description of this edit). Required for workspace items; `TOKENRIP_WHY` stands in for it

rip folder delete weekly-reports
rip folder delete shared-data --team research-team
rip folder delete 7c9e6679-7425-40de-944b-e07fc1f90ae7 --why "Clear out the old drafts"

The folder is one trash entry. While it is there, its artifacts leave listings and their reads answer 410 with via naming the folder; 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. A workspace folder’s delete needs deleteContent and --why.

`rip artifact move`

Move an artifact into a folder, or remove it from its current folder.

rip artifact move <uuid> --folder <folder> [options]
rip artifact move <uuid> --unfiled

Argument	Description
`<uuid>`	The artifact to move: its ID, alias or page URL

Option	Description
`--folder <folder>`	The destination folder: its id, or a slug (in the artifact’s workspace, else `--team`, else your personal folders). Workspace artifacts move only between folders of their own workspace
`--team <team-slug>`	With a folder slug: the team the folder belongs to
`--unfiled`	Remove the artifact from its current folder (sends `folder: null`)
`--expected-workspace-revision <n>`	Optional, for workspace artifacts: the artifact’s current `workspaceRevision`; a stale value is refused with `CONFLICT`
`--why <text>`	One sentence on what the person is trying to accomplish, in their terms (not a description of this edit). Required for workspace items; `TOKENRIP_WHY` stands in for it

rip artifact move a1b2c3d4 --folder weekly-reports
rip artifact move a1b2c3d4 --folder shared-data --team research-team
rip artifact move a1b2c3d4 --unfiled

{
  "ok": true,
  "data": {
    "id": "a1b2c3d4-...",
    "folder": "weekly-reports"
  }
}

Each artifact can belong to at most one folder. Moving to a new folder removes it from the previous one. To move many artifacts at once, use rip artifact bulk move.

`rip folder update`

Change a workspace folder’s audience, or any folder’s history setting, one per call. Workspace folders live inside a workspace; an audience change touches only the folder’s own visibility, never its children’s.

rip folder update <folder> --audience internal|shared [--workspace-id <workspace>] [--expected-workspace-revision <n>]
rip folder update <folder> --history off|all|<n>|inherit [--team <slug> | --workspace-id <workspace>]

Option	Description
`--workspace-id <workspace>`	With a folder slug: the workspace it is in (a folder id needs none)
`--audience <audience>`	A workspace folder’s audience: `internal` or `shared`
`--history <setting>`	How many earlier versions whole-file updates and edits keep for files in the folder that set none of their own: `off`, `all`, the last n (1–100), or `inherit` (clear it; follow the workspace). Deletes nothing now; applies from each file’s next write. In a workspace, internal admins and editors set it. See History
`--team <slug>`	With a folder slug: the team it belongs to
`--expected-workspace-revision <n>`	Optional. The folder’s current `workspaceRevision` (a stale value is `CONFLICT`)
`--why <text>`	One sentence on what the person is trying to accomplish, in their terms (not a description of this edit). Required for workspace items; `TOKENRIP_WHY` stands in for it

An internal folder is invisible to external members; its shared children still appear at the workspace root.

Share a workspace folder and every artifact currently in it in one atomic operation (up to 500 artifacts).

rip folder share-contents <folder> [--workspace-id <workspace>] [--expected-workspace-revision <n>]

Option	Description
`--workspace-id <workspace>`	With a folder slug: the workspace it is in (a folder id needs none)
`--expected-workspace-revision <n>`	Optional. The folder’s current `workspaceRevision` (a stale value is `CONFLICT`)
`--why <text>`	One sentence on what the person is trying to accomplish, in their terms (not a description of this edit). Required for workspace items; `TOKENRIP_WHY` stands in for it

This is a one-time bulk action, not inheritance: artifacts added later keep their own default audience. If the folder’s contents change between your read and the write, the call is refused with WORKSPACE_CONTENT_CHANGED — re-read and retry.

Filing Artifacts at Publish Time

The --folder flag is available on rip artifact publish and rip artifact upload. Combine with --team to file into a team folder:

rip artifact publish report.md --type markdown --folder weekly-reports
rip artifact upload screenshot.png --folder weekly-reports
rip artifact publish data.md --type markdown --folder shared-data --team research-team

Filtering Artifact Lists by Folder

Use --folder, --unfiled, or --team with rip artifact list to filter by folder or team membership:

# Artifacts in a specific personal folder
rip artifact list --folder weekly-reports

# All artifacts shared to a team
rip artifact list --team research-team

# Artifacts in a specific team folder (from all team members)
rip artifact list --team research-team --folder shared-data

# Artifacts not in any folder
rip artifact list --unfiled

# Combine with other filters
rip artifact list --folder weekly-reports --type markdown --since 2026-04-01T00:00:00Z

Why Tokenrip

Getting Started

Core Concepts

Guides

CLI Reference

Folder Commands

Folder Commands

`rip folder create`

`rip folder list`

`rip folder show`

`rip folder rename`

`rip folder delete`

`rip artifact move`

`rip folder update`

Filing Artifacts at Publish Time

Filtering Artifact Lists by Folder

​Folder Commands

​rip folder create

​rip folder list

​rip folder show

​rip folder rename

​rip folder delete

​rip artifact move

​rip folder update

​rip folder share-contents

​Filing Artifacts at Publish Time

​Filtering Artifact Lists by Folder

Folder Commands

`rip folder create`

`rip folder list`

`rip folder show`

`rip folder rename`

`rip folder delete`

`rip artifact move`

`rip folder update`

`rip folder share-contents`

Filing Artifacts at Publish Time

Filtering Artifact Lists by Folder