> ## 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.

# Workspace Commands

> Create and manage workspaces — owned namespaces for native notes plus included artifacts

# 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](/concepts/workspaces) for the full concept guide.

<Note>
  The `rip workspace` group is aliased **`rip ws`** — every command below works with either form (`rip ws note list research`).
</Note>

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.

```bash theme={null}
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 |

```bash theme={null}
rip workspace create research --name "Research"
rip workspace create roadmap --team acme
```

```json theme={null}
{
  "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.

```bash theme={null}
rip workspace list
```

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

***

## `rip workspace show`

Show a workspace by id or slug.

```bash theme={null}
rip workspace show <workspace>
```

```bash theme={null}
rip workspace show research
```

```json theme={null}
{
  "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.

```bash theme={null}
rip workspace archive <workspace>
```

```json theme={null}
{
  "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.

```bash theme={null}
rip workspace delete <workspace>
```

```json theme={null}
{ "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.

```bash theme={null}
rip workspace capture <workspace> "<raw text>"
```

```bash theme={null}
rip workspace capture research "websearch_to_tsquery handles phrases and negation"
```

```json theme={null}
{
  "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.

```bash theme={null}
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 |

```bash theme={null}
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-...
```

```json theme={null}
{
  "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.

```bash theme={null}
rip workspace note get <workspace> <note-slug>
```

### `rip workspace note list`

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

```bash theme={null}
rip workspace note list <workspace> [options]
```

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

```bash theme={null}
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`.

```bash theme={null}
rip workspace note archive <workspace> <note-slug>
rip workspace note unarchive <workspace> <note-slug>
```

```json theme={null}
{
  "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.

```bash theme={null}
rip workspace note delete <workspace> <note-slug>
```

```json theme={null}
{ "ok": true }
```

### `rip workspace search`

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

```bash theme={null}
rip workspace search <workspace> "<query>"
```

```bash theme={null}
rip workspace search research "tsquery"
```

```json theme={null}
{
  "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`).

```bash theme={null}
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.

```bash theme={null}
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) |

```json theme={null}
{
  "ok": true,
  "data": {
    "staleCaptures": [],
    "orphans": [],
    "promotionCandidates": [],
    "staleTopTier": []
  }
}
```

When the workspace is a [brain](/concepts/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`).

```bash theme={null}
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>
```

```bash theme={null}
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
```

```json theme={null}
{
  "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.

```bash theme={null}
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 |

```bash theme={null}
rip workspace member add research rip1abc... --role editor
rip workspace member list research
```

```json theme={null}
{
  "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.

```bash theme={null}
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`)                              |

```bash theme={null}
rip workspace item link research a1b2c3d4-...
rip workspace item add research a1b2c3d4-... --ownership owned
rip workspace item list research
```

```json theme={null}
{
  "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.