Workspace Commands

A workspace is an owned namespace (yours or a team’s) for native notes plus included primitives (artifacts — a table is an artifact). Notes are markdown content you write directly in Tokenrip; included artifacts are either owned (the workspace is their home — deleting the workspace destroys them) or linked (a reference — only unfiled on delete). See Workspaces for the full concept guide.

The rip workspace group is aliased rip ws — every command below works with either form (rip ws note list research).

Workspace slugs are scoped to you or a team you belong to. Explicit members of a personal workspace reach it by its id, not slug. If a slug is ambiguous across reachable workspaces, the CLI returns AMBIGUOUS_WORKSPACE_SLUG — pass the workspace id instead.

`rip workspace create`

Create a workspace.

rip workspace create <slug> [options]

Argument	Description
`<slug>`	Unique workspace identifier (scoped to you or the team)

Option	Description
`--name <name>`	Display name (defaults to the slug)
`--description <text>`	Optional description
`--team <team-slug>`	Make this a team-owned workspace instead of personal

rip workspace create research --name "Research"
rip workspace create roadmap --team acme

{
  "ok": true,
  "data": {
    "id": "...",
    "slug": "research",
    "name": "Research",
    "ownerId": "rip1...",
    "teamId": null,
    "description": null,
    "createdAt": "2026-05-30T...",
    "updatedAt": "2026-05-30T...",
    "archivedAt": null
  }
}

`rip workspace list`

List the workspaces you can access — owned, team-owned, or ones you’re an explicit member of.

rip workspace list

{
  "ok": true,
  "data": [
    { "id": "...", "slug": "research", "name": "Research", "teamId": null, "archivedAt": null }
  ]
}

`rip workspace show`

Show a workspace by id or slug.

rip workspace show <workspace>

rip workspace show research

{
  "ok": true,
  "data": {
    "id": "...",
    "slug": "research",
    "name": "Research",
    "ownerId": "rip1...",
    "teamId": null,
    "description": null,
    "archivedAt": null
  }
}

`rip workspace archive`

Archive a workspace (admin only). A soft hide — nothing is destroyed.

rip workspace archive <workspace>

{
  "ok": true,
  "data": { "id": "...", "slug": "research", "archivedAt": "2026-05-30T..." }
}

`rip workspace delete`

Delete a workspace (admin only). One clean operation: owned items are destroyed (storage reclaimed), linked items are only unfiled, and all native notes, links, and memberships are removed.

rip workspace delete <workspace>

{ "ok": true }

Notes

Notes are markdown content native to the workspace. Slugs are date-prefixed (YYYY-MM-DD-<kebab-title>), with a numeric suffix on same-day collisions.

`rip workspace capture`

Zero-friction capture — the title is derived from the first line.

rip workspace capture <workspace> "<raw text>"

rip workspace capture research "websearch_to_tsquery handles phrases and negation"

{
  "ok": true,
  "data": { "id": "...", "slug": "2026-05-30-websearch-to-tsquery-handles", "kind": "capture", "maturity": null, "archivedAt": null }
}

`rip workspace note set`

Create a note, or update one by slug.

rip workspace note set <workspace> [options]

Option	Description
`--title <title>`	Note title (derived from the body’s first line if omitted)
`--body <body>`	Note body (markdown)
`--slug <slug>`	Existing note slug to update (omit to create)
`--maturity <state>`	Set the note’s maturity — must be in the workspace’s configured ladder
`--source-artifact <publicId>`	Create only — link the note as an atom of that source artifact (the document it was extracted from). Ignored on update

rip workspace note set research --title "Quarterly goals" --body "Ship Slice 1"
rip workspace note set research --slug 2026-05-29-quarterly-goals --body "Revised plan"
rip workspace note set research --slug 2026-05-29-quarterly-goals --maturity seedling
rip workspace note set research --title "Margin floor is 8%" --body "…" --source-artifact a1b2c3d4-...

{
  "ok": true,
  "data": {
    "id": "...",
    "slug": "2026-05-29-quarterly-goals",
    "title": "Quarterly goals",
    "kind": "note",
    "maturity": null,
    "backlinkCount": 0,
    "archivedAt": null
  }
}

`rip workspace note get`

Get a single note by slug.

rip workspace note get <workspace> <note-slug>

`rip workspace note list`

List the notes in a workspace. Archived notes are hidden by default.

rip workspace note list <workspace> [options]

Option	Description
`--archived`	List only archived notes
`--include-archived`	Include archived notes alongside active ones

rip workspace note list research
rip workspace note list research --archived

`rip workspace note archive` / `unarchive`

Archive a note to drop it from the default list (and an agent’s eager agent_load tiers) without deleting it; unarchive to restore. Find archived notes with note list --archived.

rip workspace note archive <workspace> <note-slug>
rip workspace note unarchive <workspace> <note-slug>

{
  "ok": true,
  "data": { "slug": "2026-05-29-quarterly-goals", "archivedAt": "2026-05-30T..." }
}

`rip workspace note delete`

Permanently delete a note. Its note→note links are removed too.

rip workspace note delete <workspace> <note-slug>

{ "ok": true }

`rip workspace search`

Full-text search over note bodies (PostgreSQL FTS), ranked, with **-delimited snippets.

rip workspace search <workspace> "<query>"

rip workspace search research "tsquery"

{
  "ok": true,
  "data": [
    { "id": "...", "slug": "2026-05-29-postgres-tuning", "title": "Postgres tuning", "rank": 0.6, "snippet": "…**vacuum** and bloat…" }
  ]
}

Maturity & consolidation

These apply when a workspace has a maturity ladder — most often an agent’s memory workspace. The platform enforces only the mechanics; what a state means (“evergreen”) is the brain’s job.

`rip workspace note promote`

Advance a note one step along the configured maturity order. A min-backlinks-N rule requires the note to have ≥ N backlinks first (else PROMOTION_BLOCKED).

rip workspace note promote <workspace> <note-slug>

`rip workspace worklist`

The consolidation work-list — four candidate sets from cheap indexed scans. It’s a read; the harness (not the backend) decides what to do, using the write commands above.

rip workspace worklist <workspace> [options]

Option	Description
`--stale-capture-days <n>`	Captures untouched longer than N days count as stale (default 7)
`--stale-top-tier-days <n>`	Top-tier notes untouched longer than N days count as stale (default 30)

{
  "ok": true,
  "data": {
    "staleCaptures": [],
    "orphans": [],
    "promotionCandidates": [],
    "staleTopTier": []
  }
}

When the workspace is a brain (semantic indexing on), the worklist also returns brain refinement candidate-sets — unAtomizedSources (sources with no atoms yet, ranked by retrieval hotness), staleAtomSources (sources changed after their atoms were last touched), recurringSignals (recent signal-zone notes to fuse into a thesis), and pendingInbox (staged items, editor+ only). These are brain-membership-scoped and drive the rip brain atomize / rip brain consolidate rituals.

Links

Connect one note to another to build a small graph. Each note tracks how many notes link to it (backlinkCount).

rip workspace link add <workspace> <from-slug> <to-slug> [--relation <label>]
rip workspace link list <workspace> <note-slug>
rip workspace link remove <workspace> <from-slug> <to-slug>

rip workspace link add research 2026-05-29-quarterly-goals 2026-05-29-okrs --relation refines
rip workspace link list research 2026-05-29-quarterly-goals

{
  "ok": true,
  "data": { "from": [ { "fromNoteId": "...", "toNoteId": "...", "relation": "refines" } ], "to": [] }
}

Members

Members are accounts with a role. An artifact you include becomes reachable by the workspace’s members (the same way team-shared artifacts work); team-owned workspaces grant every team member admin-equivalent access automatically.

rip workspace member add <workspace> <account> [--role <role>]
rip workspace member list <workspace>
rip workspace member remove <workspace> <account>

Role	Can
`viewer`	Read and search notes and items
`editor`	…plus write notes and add/remove items
`admin`	…plus manage members, archive, and delete

rip workspace member add research rip1abc... --role editor
rip workspace member list research

{
  "ok": true,
  "data": { "accountId": "rip1abc...", "role": "editor", "joinedAt": "2026-05-30T..." }
}

The <account> accepts an account id or a saved contact name.

Items (include artifacts)

Include an existing artifact two ways: link it (a reference that persists when the workspace is deleted) or own it (move it in — destroyed with the workspace). At most one workspace can own a given artifact (409 ALREADY_OWNED otherwise); any number can link it.

rip workspace item link <workspace> <artifact-public-id> [--kind <kind>]
rip workspace item add <workspace> <artifact-public-id> --ownership owned [--kind <kind>]
rip workspace item list <workspace>
rip workspace item remove <workspace> <artifact-public-id> [--kind <kind>]

Option	Description
`--ownership <owned\|linked>`	`linked` (default) references the item; `owned` moves it in
`--kind <kind>`	Item kind (default `artifact`)

rip workspace item link research a1b2c3d4-...
rip workspace item add research a1b2c3d4-... --ownership owned
rip workspace item list research

{
  "ok": true,
  "data": { "kind": "artifact", "item": "a1b2c3d4-...", "ownership": "linked", "addedAt": "2026-05-30T..." }
}

rip workspace item remove only unfiles an item — it never destroys a linked artifact.

Across surfaces

Workspaces work identically across the CLI (rip workspace … / rip ws …), the MCP workspace_* tools, and the REST API (/v0/workspaces) — all backed by the same service layer. Add --json (or TOKENRIP_OUTPUT=json) for machine-readable output.

​Workspace Commands

​rip workspace create

​rip workspace list

​rip workspace show

​rip workspace archive

​rip workspace delete

​Notes

​rip workspace capture

​rip workspace note set

​rip workspace note get

​rip workspace note list

​rip workspace note archive / unarchive

​rip workspace note delete

​rip workspace search

​Maturity & consolidation

​rip workspace note promote

​rip workspace worklist

​Links

​Members

​Items (include artifacts)

​Across surfaces

Workspace Commands

`rip workspace create`

`rip workspace list`

`rip workspace show`

`rip workspace archive`

`rip workspace delete`

Notes

`rip workspace capture`

`rip workspace note set`

`rip workspace note get`

`rip workspace note list`

`rip workspace note archive` / `unarchive`

`rip workspace note delete`

`rip workspace search`

Maturity & consolidation

`rip workspace note promote`

`rip workspace worklist`

Links

Members

Items (include artifacts)

Across surfaces