Workspace Commands
rip workspace (alias rip ws) manages workspaces: the authoritative home for a project’s artifacts, tables, flat folders, and tasks, with internal/shared audience and members you add or invite by email. A <workspace> argument or --workspace-id takes the workspace’s id or slug (rip workspace load tokenrip-social), in any case. A slug none of your workspaces has is WORKSPACE_NOT_FOUND, as an unknown id is; a slug two of them share is AMBIGUOUS_REFERENCE, and the error prints each candidate’s id, home and name: use the id. See Workspaces for the model.
Every write states why. Each command that writes workspace content takes
--why "<one sentence>": what the person you work for is trying to accomplish, in their terms, not a description of the edit. “Set launch prices the team can defend to finance” is a goal; “Update row 4” is not. A script with one purpose can set TOKENRIP_WHY instead; the flag wins. A write without it is refused with WHY_REQUIRED and changes nothing. If your rip has no --why flag, run rip self-update.Workspaces
rip workspace create
A team-owned workspace needs a paid plan, and each owner may keep up to a maximum number of live workspaces. When the owner has no room, the command fails with
WORKSPACE_LIMIT_REACHED and prints Workspaces: <used> of <limit> (<plan>). At the maximum, deleting a workspace makes room.
role (admin | editor | viewer), membership (internal | external), the audiences you can see, and a capabilities map. Trust the map, not the role name.
rip workspace list · show · update
--history (admins) sets how many earlier versions whole-file updates and edits keep across the workspace, unless a folder or file sets its own: off (the default), all, the last n (1–100), or inherit (clear it; reads as off). It deletes nothing now and applies from each file’s next write. See History.
List/show print the full id, slug, personal/team home, and capabilities; names can repeat. Clarify unresolved ambiguity before selecting. To see who worked here recently, use rip workspace sessions.
rip workspace delete
deleteWorkspace and nothing else: the workspace does not need to be empty. It prints the purge date; --json returns { type, id, deletedAt, purgeAt }. While the workspace is in the trash, every command on it answers WORKSPACE_DELETED (410) with the purge date, it leaves rip workspace list, and its slug stays held. After the purge date it is removed for good.
rip workspace member …
- Guests. Everyone added is a guest, who sees shared items only, as
--role editor(the default) or--role viewer(read-only). Internal access comes from owning the workspace or being in its team: to give someone everything, add them to the owning team (rip team add <team> <email>), where each member is billed.--membership internalis refusedINTERNAL_NEEDS_TEAM, naming that path;--membership externalchanges nothing, and the flag is going away. - What the person gets. An email from Tokenrip naming the inviter (the verified address of the person behind your account), the workspace and the access, with your note (plain text, at most 280 characters), a link to the invite page and a line to paste into an AI assistant. They sign in with the six-digit code Tokenrip emails to that address, in the browser or through their agent, and every invite waiting on the address becomes their membership. There is no accept step.
- Until then the row has
status: "invited", the address inemail, and aninviteUrl. Nothing in the email or the link signs anyone in, so share theinviteUrlfreely. - Existing users (their verified address, alias or account id) are added at once. An add by address emails them that they were added; an add by alias or account id emails them only when their account has one verified person and yours has one to send from.
- Who may. Internal admins and editors add and invite; only admins change a role (
set-role) or remove.set-roleandremovetake the rowidfrommember list, which stands alone, or an account id, alias or email address with--workspace-id(an address names the row of the person who holds it, on their primary account, or the row an add or invite by that address made; for a member on another of their accounts, use the rowid);removeon an invite cancels it.set-rolechanges--role; the member stays a guest. An alias or account id that names no account isACCOUNT_NOT_FOUND; removing someone with no row in the workspace changes nothing. - Limits. Invite emails are limited per person (by default 20 an hour, one per invite an hour, one per address an hour); past them an add is refused
RATE_LIMITED, except an add of an existing account by alias or id without a note, which goes ahead without the email. An add by email needs a verified person behind your account to send from (NO_OPERATOR/OPERATOR_AMBIGUOUS).
WORKSPACE_MEMBER_INTERNAL); when a guest later joins the owning team, their guest row is consumed. A removal records your why on each task hold it stops.
rip workspace adopt
Move standalone content you own into the workspace — atomic, no copy, identity and history preserved.
Old team shares on the content are removed. Refused before any effect:
MIXED_OWNERSHIP (not yours), ALREADY_IN_WORKSPACE, INELIGIBLE_STORAGE (public assets or independently hosted content), WORKSPACE_BULK_LIMIT (more than 500 artifacts). Sharing an adopted artifact exposes every version it keeps. There is no move-out.
rip workspace pin add · remove
Ordered markdown that every load returns as read-first context (internal editors, max 20). The pin goes in the artifact’s own workspace. Pins record no change and take no --why.
rip workspace load
Read bounded context when you start work in a workspace, on every run: storage against the plan, your instructions here, what waits on you, open tasks, the workspace’s agents, pins, artifacts, the latest changes (who, what, which item, and why, newest first) and how many are unread, recent sessions, and your browser link. Nothing is started or ended.
WORKSPACE_DELETED (410). The response is bounded and every collection has its own continuation field:
Human output (no
--json) prints all of this: the header Workspace: <name> (<slug>) [<id>], a Can: line of capabilities, the browser link, a Storage: line (this workspace’s bytes, then the payer’s plan and its use, such as account on the Free plan uses 860 MB of 1 GB (86%), with the notice beneath it when there is one), then Instructions (v<n>): with the whole text (or “No instructions here yet: your person writes them in the dashboard, Members & settings”), Waiting on you (<n>): with each task’s reason, the agents with their handles, then each pin, recent sessions printed the way rip workspace sessions prints them, open tasks, Latest changes (<n>): newest first (time, who, action, item and id, with the why beneath), then, when any are unread, <n> unread since your last acknowledgement: rip workspace changes <slug> (1000+ past the count’s cap), the artifact index, and a rip workspace load <id> --<continuation> line for each list that continues. A small pin is printed inline. A large pin arrives as a reference; the human output prints the exact command to read it, rip artifact cat <publicId> --version-id <versionId> (in --json, a pin has content.content when inline, otherwise content.versionId).
Loading is idempotent: it reads your position in the change feed only to count what is unread, and never moves it. To catch up on what is unread, read rip workspace changes (below), which reads it in order and reports history gaps and access changes, then acknowledge. Sequences are positions, not visible-event counts or write revisions.
Load and show take no session flags:
--operation-id and --session-id on load and --session-cursor on show are unknown options. There is no session to start or end: sessions record themselves, and open work stays in tasks (where the next agent picks up).rip workspace sessions
why) followed by the changes made for it:
- Who. Your own account’s work reads
You:You · <agent name> (<harness>),You · <harness>for your own work without a key, plainYouwithout a harness, orYou · in the browser. Someone else’s reads~alias's agent · <harness>for their agent (other people’s key names are never shown),~alias · in the browser, or~aliasalone. Harnesses print as names: Claude Code, Codex, CLI, Cowork. unreadmarks a session with changes after your key’s lastrip workspace ack.- Each change names its actions (
created,edited,rows_changed,details_changed,moved,audience_changed,version_deleted,versions_pruned,completed…; changes from before October 2026 may readupdated), the item with its full id, the versions it created ((deleted)for a version removed since; past five, the first and the latest four with…between), and row counts. An edit gets onerip artifact diffcommand for the whole change, from its first version to its last (--from-version-id <first> --version-id <last>), so you read everything the step changed at once. A file the step created gets none: all of it is new. An item in the trash reads(gone)after its title; one deleted for good or out of your reach reads(gone)alone. - A person’s dashboard edits read “in the browser”; older changes without a why read “no stated goal”. The human output ends with the
--cursorcommand for the next page.--jsonreturns the Sessions response.
Where the next agent picks up
There is no note to write when you stop. Leave open work in tasks:rip task done what you finished, rip task stop what you hold and won’t finish, and for a half-done task, rip task update --body with how far it got. A proposal stays In review until someone decides it. The next agent loads the same workspace and reads those tasks, the whys on the changes and these sessions.
rip workspace view context · view open
When the operator opens your browserLink, that tab follows your agent key in this workspace. Read what it shows before acting on “this document”; then write by artifact id with the precondition it reported.
view context returns state: paired | disconnected and, when paired, the tab’s saved savedArtifactId, savedVersionId, savedRevision, dirty, following, and contextGeneration. view open asks the tab to navigate and returns a receipt: queued (following and clean), deferred (the person is editing or paused, or the context moved — they get an Open button), applied, or disconnected. view open finds the tab in the artifact’s own workspace. --operation-id is this navigation request’s optional retry identity: repeating it returns the same receipt; without it the server makes one, and a retry is a new request. Ordinary writes never move the tab; nothing you request can discard a draft. Revoking your key or losing access disconnects the tab.
rip workspace changes · ack
changes is where you catch up on what load counts as unread. It returns a page (default 50, max 100) of authorized events since your credential’s acknowledged position, oldest first, within a catch-up window that your first changes call opens and that holds until you have acknowledged through it, with a deliveryToken, hasMore, historyGap (retention pruned past your position — reload), and refresh (required when your access changed). Reading, loading, and polling never acknowledge; only ack advances the position, and only through a delivered page. While a page is outstanding a new one is refused (WORKSPACE_PAGE_UNACKNOWLEDGED) — replay it by passing its token to changes. Tokens expire after 10 minutes (INVALID_WORKSPACE_DELIVERY).
Human output groups consecutive changes under one heading per person and why, in the words sessions use, and names each item with its public id; Access changed: re-read before continuing. follows when refresh is required, and History gap: older changes were pruned. on a historyGap:
--json, each item carries type, actor (with alias), subject (type, id, title; an artifact’s id is its public id), payload, why, agent, mine and createdAt. See Read Changes.
Workspace content uses the ordinary commands
Artifacts, tables, folders, and tasks inside a workspace are written with their normal commands plus workspace flags. New artifact, folder, and task creation needs no revision; insert-only rows need none, and an upsert overwrites its match unless you send the row’s revision. Workspace creation omits standalone visibility/sharing fields and keeps explicit workspace identity and audience; to open one file to anyone with its URL, publish it, then patch it with--visibility link. Every write states --why. A write composed from what you read carries the precondition the read surface reported: replacing a file’s whole content that someone else wrote (--expected-version-id: another agent or key, a person in the browser, or a write from before this release), a row or task update (--expected-revision), a patch of description or metadata (--expected-workspace-revision); PRECONDITION_REQUIRED when missing. Appending (rip artifact append) and edits (--find/--replace) never need one. Every other write states its whole outcome and takes its revision optionally. A stale precondition is CONFLICT (with the current value).
Tasks
Tasks live in a workspace. See Tasks for the model: tags, review rounds, links, comments and the claim loop. Every write takes--why (or TOKENRIP_WHY).
rip task list · show · timeline
list prints one row per task: status, type/step, title, then who holds it, who it waits on, or who it is for, with “round 2 · sent back” when its latest round says so. --mine lists tasks for you or held by you; --reviewer me lists reviews In review addressed to you. show prints who it is for and who reviews it, the latest round (its draft text and files, the decision and its comment), the approved text and files to carry out, the result and links, the children and the newest 30 timeline entries. --round <n> adds that round whole, with each draft file’s version and the rip artifact diff --base command against its base. timeline pages the whole timeline, newest first: every round, comment (with its id) and step, with who took it and why.
rip task add · update
--assignee and --reviewer take a person (account id or alias) or agent:<handle> from rip workspace load; the reviewer may be the assignee, never the one who proposes. --link adds a context link (a file or page the work uses); --remove-link removes one by target, and result links are never removed. While a task is In review, a new --reviewer re-addresses the open review and a new --assignee is whom a send back returns it to.
rip task start · stop · done · cancel · reopen
start with an id takes that task under your lease (0.25–72 hours, default 2); starting your own again renews it. With --workspace-id instead, it claims the oldest To do task matching the tags: with no tag, only a task naming this agent; with a tag, also one for no one or for your person with no agent named. It prints “No task” when none matches. Use no tag for your own queue and --type with --step for routine work; a type alone also matches approved tasks waiting at the next step. Renew during long work by starting the task again before its lease runs out.
stop puts a task you hold back in To do, or withdraws your own proposal In review (the task stays). done completes a task that is free or yours, with result links. cancel ends a task; on an In review task it is how to say no to the proposal, and the reviewer may do it (the round closes cancelled). reopen brings a done or cancelled task back; a proposal cancelled In review and still for its proposer goes back In review on a new round.
rip task propose · decide · report
propose opens a review round: a new task (with --title and --workspace-id or --parent-id), or a round on a task that is free or yours, or your own open proposal. --draft-artifact names a file the draft is made of, at a version number or id (else its current one), repeatable, in order, at most 10. --then is the step an approval moves the task to, for whoever does it; without it, the approved task comes back to you. In review: stop there; a later rip workspace load lists it under Waiting on you once it is decided.
decide takes exactly one of --approve and --send-back (with a required --comment). To say no, cancel the task: rip task cancel <task-id> [--reason "<text>"]. --edited-draft-file is the text to carry out instead of the draft, and --edit-artifact a draft file at the later version you saw and approve. --decline and the retired --skip are unknown options whose message names rip task cancel.
report records work that needed no approval (born Done), or adds a later result to a Done task.
rip comment add · update · delete
rip task timeline prints each comment’s id). Only its author changes or deletes it. Nobody is emailed. See Comments.
Across surfaces
These commands map to the/v0/workspaces, /v0/tasks and /v0/comments REST routes and the MCP workspace_*, task_* and comment_* tools (rip workspace sessions is workspace_sessions, rip comment add is comment_create). Browser tab pairing exists only in the dashboard. Add --json for machine-readable output.