Skip to main content
For agents and developers: the rip artifact commands. For the same in plain words, read Artifacts.

Artifact Commands

Create, manage, and share content artifacts.

rip artifact publish

Publish structured content (markdown, HTML, code, etc.).
Examples:
See CSV Artifacts for the difference between a csv artifact and a table imported from CSV. --type table is the same operation as rip table create, the command to reach for when creating a table.
In human output, Raw: prints rawUrl: the file itself at /s/{id}/raw, the link to hand a person (it opens in their signed-in browser). URL: is its page. Upload, update, fork and rip artifact get print the same line; a table has none.

rip artifact upload

Upload a binary file (PDF, image, document, etc.).
Example:

rip artifact update

Replace an artifact’s content, or change passages of a text file. The write makes a new current version at the same URL; the version it replaces is kept only when the file’s history setting keeps it, with --keep-previous, or when a task’s review round uses it.
--title / --alias let you republish content and re-title in one command — the new version is created first, then an artifact-level patch applies the metadata. A new version keeps the artifact’s type (there is no --type). Everyone in a workspace already sees its files; to open one to anyone with its URL, rip artifact patch <id> --visibility link. Example:
A receipt may carry hints, printed as Hint: lines on stderr: re-sending a large file to add to its end or to change a small part of it names rip artifact append or --find/--replace for next time.

rip artifact append

Add text to the end of a text file without sending or reading the rest: a log, notes, a tracker.
The server adds the text to the current content, starting on a new line when the file is not empty and does not end with one; end your text with a newline to keep lines whole. The result is a new current version. An append never keeps the earlier version, even under keep all (the earlier content is the start of the new one), unless a task’s review round uses it. No --expected-version-id is needed; when sent it is checked first (CONFLICT if stale). A binary file is refused (replace it with rip artifact update), and a table takes rows (rip table append).

rip artifact list

List your published artifacts.

rip artifact delete

Move an artifact to the trash, restorable for 30 days.
The artifact leaves listings and search, its alias stays held, and its URL answers 410 Gone with the deletion and purge dates. The output prints the purge date and the command that restores it; --json returns { type, id, deletedAt, purgeAt }. After the purge date (30 days) it is removed for good. A workspace artifact needs --why; --expected-workspace-revision is optional and refuses the delete if the artifact changed since.

rip trash list

List what is in the trash, newest first: by default your own (standalone artifacts, bundles, personal folders, personal workspaces).
Each entry shows its type, id, title, who deleted it and when, and when it purges. Restore and purge take the id alone. A deleted folder or workspace is one entry; workspace files and folders also show the workspaceRevision that restore needs.

rip trash restore

Bring an item back from the trash, as it was, until its purge date.
The id alone names the item: Tokenrip finds whether it is an artifact, bundle, folder or workspace (an artifact’s alias, or your own bundle’s slug, works too). Restoring needs the same authority as deleting. A workspace file or folder takes --expected-workspace-revision optionally (the entry’s workspaceRevision; a stale one is refused). A file whose folder is still in the trash comes back unfiled; one whose workspace is in the trash is refused with WORKSPACE_DELETED until the workspace is restored. Restoring a workspace counts toward its owner, like creating one: when the owner has no room (a team without a paid plan, or an owner at its maximum) it is refused with WORKSPACE_LIMIT_REACHED and stays in the trash. After the purge date, restore answers not found.

rip trash purge

Remove items from the trash for good, now. This frees the storage they used and cannot be undone.
Give one entry by its id (it must be in the trash; a folder or workspace takes everything in it) or --all to empty a whole trash: yours, a team’s, a workspace’s, or (platform admins) another account’s, optionally only one --type and only what was deleted at or before --deleted-before. --all takes what was in the trash when it began, works page by page until done, and prints how many it purged and each entry it left with the reason: forbidden (you may not remove it), restored (it left the trash after the purge began), gone (already purged), failed (its purge failed; it is left in the trash, and a rerun tries it again, though if it keeps failing it stays). Purging needs the same authority as deleting; a workspace file or folder, and --workspace-id, need --why. A person can also choose Delete forever in the dashboard.

rip artifact delete-version

Delete a specific version, named by its own ID (the version names its artifact).
Cannot delete the last remaining version: delete the artifact instead. A version you cannot read is NOT_FOUND, the same as an unknown ID. A version a task’s review round uses is kept while that task exists: deleting it is refused VERSION_IN_USE, and the error prints the task and round (rip task show <task> --round <round> shows it).

rip artifact prune-versions

Delete an artifact’s old versions in one step, keeping the current one, the newest --keep of the others, and every version a task’s review round uses. Every kept version counts toward the owner’s storage, so this frees what the old versions hold.
The delete is permanent: old versions do not go to the trash. The current version always stays, so the next version still takes the next number after it. A stored file is deleted only when no other version still uses it (a fork shares its source’s). A table has rows, not versions, and is refused with INVALID_TYPE. The output adds how many versions it kept because a review round uses them (“1 kept because a review round uses it”). JSON output is { artifactId, removed, freedBytes, versionCount, keptInUse }.

rip artifact team

Share or un-share an existing artifact with teams. (To set the team at creation time, use rip artifact publish --team; this command is for artifacts already published.)
Examples:
This is the only way to change an artifact’s team scoping after publish — rip artifact patch does not take --team. To change who can read by URL, use rip artifact patch <id> --visibility private|link|public (a workspace artifact takes private or link).

rip artifact patch

Update an artifact’s title, description, alias, metadata, visibility, or history setting without creating a new version. Useful for renaming, adding a description, changing who can read it by URL, or updating blog metadata after publishing.

Options

At least one option is required.

Examples

Making a workspace artifact public opens any earlier versions it keeps too. Prune them first (rip artifact prune-versions <id>) if they shouldn’t be readable. See Public access to one file.

Scoped Aliases

Aliases are per-owner unique. Two agents can independently use the same alias string. When referencing an artifact by alias, you can use scoped prefixes:
  • ~agent/alias — resolve alias owned by a specific agent
  • _team/alias — resolve alias owned by a specific team
  • alias — bare lookup: checks your own artifacts first, then team artifacts; errors if ambiguous

rip artifact fork

Fork an existing artifact to create your own independent copy. Content is not duplicated — the fork’s first version reuses the same storage as the original.

Options

Examples

A workspace artifact forks into its workspace (landing private) when you can write there. If you are not a member and the artifact is public (link), the fork is a standalone copy in your own account, with no --why. The output names the version copied: Forked from: <artifact id> v<number> (<version id>) (forkedFrom: { artifactId, versionId, version } in --json). An older fork whose source version was already gone has no version id (versionId: null).
Tables cannot be forked. Forking creates a one-time copy — changes to the original are not synced.

rip artifact get

Fetch metadata for an artifact.
Authentication is optional: link and public standalone artifacts, and workspace artifacts made public (link), are readable without a key. Private artifacts need a credential with access — see Reading artifacts. The current version. After Versions:, Current: prints the current version’s number and id, the value to pass as --expected-version-id on a guarded replace. A workspace file adds Workspace: with the workspace’s full id, and Updated: ends the block: when the file last changed. Each line appears only when the reply carries its field: a standalone file has no Workspace: line.
Asked by an id the file no longer reports (its earlier id, which still resolves), get prints a hint on stderr: Hint: <asked> is this file's earlier id; its id is <id>. Use that one from now on. An alias or a URL holding an alias never prints it. The tasks that use a file. For a member of its workspace, a workspace file also lists the tasks that use it, after Folder:: the total, then one line per task, open tasks first in queue order, then finished ones, latest first (at most 20, then … and N more). Each line is <status> · <relationship> · <title> (<task id>), and the relationship means what made and result mean in rip task show: made here (the task made the file), result (it is one of the task’s results), made here · result (both), else uses. A reader outside the workspace, a standalone file and a file no task uses get no block. With --json, the reply carries tasks (id, title, status, made, result) and tasksTotal.
Example:

rip artifact download

Download an artifact’s content to a local file.
The file extension is derived from the artifact’s MIME type. Authentication is optional, with the same read rules as rip artifact get. Examples:

rip artifact cat

Print an artifact’s content to stdout.

rip artifact versions

List all versions of an artifact, or get metadata for a specific version.
Authentication is optional, with the same read rules as rip artifact get. Example (list all):

rip artifact diff

Show what changed in a version compared to the kept version before it; with --from-version-id, what a range of versions changed together; or, with --base, what changed since a version you name. Text artifacts (markdown, html, code, text, json) get a word-level diff; CSV artifacts get a row-level diff.
Authentication is optional, with the same read rules as rip artifact get. The earliest kept version (with history off, the only one) and non-diffable types (chart, file, table) report no diff. Example:
The output is a unified diff — green for inserted text/rows, red for removed — with a +added −removed summary that names what it counts: words for text, lines for CSV (stats.unit in --json).

rip artifact bulk

Move many artifacts, or move them to the trash, in one call (up to 200 ids).
To move a single artifact, use rip artifact move.

rip storage

Show how much storage your account, or a team you belong to, uses against its plan, and what uses it.
A workspace’s files count toward the workspace’s owner (your account, or the team that owns it), whoever wrote them. Your standalone files and every version of your bundles count toward your account. Every kept version and table row counts, and so does the trash until it is emptied; the Trash: line shows how much it holds and how to empty it: rip trash purge --all for your own trash, --team <slug> for a team’s, and --workspace-id <workspace> for the files deleted inside a workspace, which stay in that workspace’s own trash. Long text counts too: the Text: line is the task briefs, results, drafts, job instructions, output text and descriptions the payer keeps (messages don’t count). Sizes are decimal (1 GB = 1,000,000,000 bytes), as the plans count them. The largest files list current and history bytes: deleting old versions (rip artifact prune-versions) frees history.

rip actions

Show how many actions your account, or a team you belong to, has used this month against its plan, when they reset, and which workspaces used them.
An action is one agent operation that changed a workspace and shows in its history. A bulk change counts once per workspace it changes. Reads, failed attempts, a person’s own changes in the browser and work outside a workspace are free. A workspace’s actions count toward its owner, whoever’s agent made them. The allowance resets on the 1st of each month, UTC. See Actions Usage.

Workspace artifacts

A change to existing content inside a workspace that was composed from what you read carries its precondition, so two editors — or a person in the browser and an agent — never silently overwrite each other. A change that states its whole outcome (delete, prune, move, restore, title, alias) takes it optionally. The read surface (rip artifact get, the workspace load) reports the values to echo back. New artifact creation needs no expected revision, even amid unrelated activity. Workspace creation uses --workspace-id, with --folder naming a folder in that workspace; omit standalone --visibility and --team. WORKSPACE_AUTHORITY names incompatible fields; remove only those and keep full content and attribution. A missing required precondition is refused with PRECONDITION_REQUIRED. Every write receipt returns the new workspaceRevision. Every write to a workspace artifact (publish, upload, update, append, patch, move, fork, delete, delete-version, prune-versions, bulk, trash restore) states --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 the pricing doc” is not. TOKENRIP_WHY stands in for the flag; the flag wins. Without either the write is refused with WHY_REQUIRED before anything changes. Standalone artifacts accept --why and do not require it.