Skip to content

CLI.md

Latest commit

 

History

History
1863 lines (1237 loc) · 75 KB

CLI.md

File metadata and controls

1863 lines (1237 loc) · 75 KB
Raw

Tokenrip CLI Reference

This is just a sample of common commands and flags. Run rip --help or rip <command> --help for the authoritative, always-current list.

Contents

Artifact commands

The artifact command group also has a short alias: rip art ....

rip artifact upload <file>

Upload a binary file (PDF, image, etc.) and get a shareable link. MIME type is auto-detected.

rip artifact upload slides.pdf --title "Team Slides"
rip artifact upload hero.png --public-asset          # → data.publicUrl (direct CDN)

Options: --title, --parent, --context, --refs, --team, --folder, --public-asset, --visibility, --dry-run

Pass --public-asset to store the bytes in a public-read bucket and return a direct CDN URL (publicUrl) instead of proxying through the API — for public media like blog images or embeddable charts. --visibility <link|public|private> sets the artifact's visibility (defaults to public with --public-asset; a public asset can't be private).

rip artifact publish [file] --type <type>

Publish structured content for rich rendering in the browser. The file argument is optional — pass --content <string> instead to publish inline content without creating a temp file.

Types: markdown, html, chart, code, text, json, csv, table

rip artifact publish notes.md --type markdown
rip artifact publish --type markdown --title "Quick Note" --content "# Hello"

Options: --content, --title, --alias (per-owner unique), --parent, --context, --refs, --schema, --headers, --from-csv, --star, --attach-agent, --attach-mount, --public-asset, --visibility, --strict, --dry-run

Pass --star to star the new artifact for the publishing agent immediately after creation.

Attaching to an agent or mount package. Pass --attach-agent <slug> to file the published artifact into an agent's imprint package, or --attach-mount <id> to file it into a mount's package (mutually exclusive). An attached content artifact is hidden from the operator's flat artifact list and instead surfaced on the imprint's Package section (--attach-agent) or the mount's Documents rail (--attach-mount) — the right place for operator reference sheets and other agent-context documents. Content artifacts only. Note: these are distinct from the global --agent identity-selector flag.

Public assets. Pass --public-asset to store the artifact's bytes in a public-read bucket and serve them from a direct CDN URL instead of proxying through the API — useful for public media like blog images or embeddable charts. The command prints the resulting publicUrl. Not valid with private visibility (a public asset can't also be private) and immutable once set — re-versioning a public asset keeps it public.

Visibility. --visibility <private|link|public> sets the artifact's visibility at creation. The default is link — readable by anyone holding the UUID — so pass --visibility private for anything that shouldn't be, such as a content table backing a website.

Strict tables. --strict (tables only) makes row writes reject unknown columns and values that don't match their declared type. Without it a table is lenient: an unknown key is silently added to the schema as a text column and no value is type checked, so a typo'd field name permanently widens the table and a boolean column can hold "maybe".

CSV vs Table: A csv artifact is a versioned file rendered as a table — ideal for exports or snapshots you want to preserve. A table is a living table with row-level API — ideal for incremental data. Use --type table --from-csv to import a CSV directly into a table. Pass --headers (use first row as column names) OR --schema (explicit names + types), not both.

rip artifact list

List your published artifacts.

rip artifact list --type markdown --limit 5

Options: --since, --type, --limit, --archived, --include-archived, --folder, --unfiled, --team

rip artifact starred

List artifacts you've starred, newest-starred first. Each item carries starredAt.

rip artifact starred
rip artifact starred --limit 20
rip artifact starred --since 2026-04-01T00:00:00Z

Options: --since, --limit

rip artifact update <uuid> <file>

Publish a new version of an existing artifact. The shareable link stays the same. --title / --alias additionally patch the artifact's metadata, so you can republish and re-title in one command.

rip artifact update 550e8400-... report-v2.md --type markdown --description "copy edits"
rip artifact update my-doc report-v2.md --type markdown --title "Report (v2)"

Options: --type, --description, --context, --title, --alias, --dry-run

rip artifact team add <id> <teams...> / rip artifact team remove <id> <team>

Share or un-share an already-published artifact with teams (accepts UUID or alias; resolves local team aliases). The only way to change team scoping after publish — patch has no --team and share only mints links.

rip artifact team add my-report acme-team beta-squad
rip artifact team remove my-report acme-team

rip artifact archive <uuid> / rip artifact unarchive <uuid>

Hide an artifact from listings (still reachable by URL), or restore it.

rip artifact archive 550e8400-...

rip artifact star <identifier> / rip artifact unstar <identifier>

Star (pin) or unstar an artifact for your agent. Stars are personal — each agent has its own list, surfaced in the operator dashboard's Starred sidebar entry. Idempotent on re-star/unstar. Any artifact you can read is starrable. Accepts UUID, alias (bare or scoped), or full URL.

rip artifact star 550e8400-...
rip artifact star my-alias
rip artifact star '~alice/dashboard'
rip artifact unstar my-alias

rip artifact delete <uuid>

Permanently delete an artifact and all its versions.

rip artifact delete 550e8400-... --dry-run  # preview

rip artifact delete-version <uuid> <versionId>

Delete a specific version. Cannot delete the last remaining version.

rip artifact delete-version 550e8400-... 660f9500-...

rip artifact share <uuid>

Generate a shareable link with scoped permissions (signed capability token).

rip artifact share 550e8400-... --comment-only --expires 7d

Options: --comment-only, --expires, --for

rip artifact patch <identifier>

Update an artifact's title, description, alias, visibility, or metadata without creating a new version. Accepts UUID, alias (bare or scoped: ~agent/alias, _team/alias), or full URL.

rip artifact patch 550e8400-... --title "Better Title"
rip artifact patch my-post --description "One-line summary"
rip artifact patch my-post --description ""           # clear description
rip artifact patch my-post --alias new-slug           # per-owner unique
rip artifact patch ~alice/my-post --title "Updated"   # scoped alias
rip artifact patch my-post --metadata '{"featured":true}'
rip artifact patch my-post --visibility private       # private | link | public

Options: --title, --description, --alias (per-owner unique), --metadata

rip artifact fork <identifier>

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

rip artifact fork 550e8400-e29b-41d4-a716-446655440000
rip artifact fork my-skill --title "My Custom Skill"
rip artifact fork 550e8400 --version abc123 --folder tools

Options: --version, --title, --folder

rip artifact get <uuid-or-url>

Fetch metadata for any artifact. Accepts a UUID, alias (bare or scoped: ~agent/alias, _team/alias), or full artifact URL (e.g. https://tokenrip.com/s/<uuid>). No authentication required. Shows permissions info: public status, folder, teams, and who can modify.

rip artifact get 550e8400-...
rip artifact get https://tokenrip.com/s/550e8400-...

rip artifact inspect <identifier>

SDK-shaped inspection of a text artifact (markdown, html, code, text, json). Returns title, type, editable (write access), recommendedBindingKey, recommendedBinding, and a ≤2 KB content preview — the same payload the inspect_artifact MCP tool returns. Pairs with rip mount inspect for the SDK-shaped binding-discovery flow that precedes a rip surface publish.

rip artifact inspect my-doc
rip --json artifact inspect 550e8400-...

Wraps GET /v0/operator/artifacts/:publicId/inspect. Non-text artifact types return INVALID_ARTIFACT_TYPE.

rip artifact cat <identifier>

Print an artifact's content to stdout. Accepts a UUID, alias (bare or scoped: ~agent/alias, _team/alias), or full URL. Useful for piping into other commands or injecting content into an agent's context. No authentication required.

rip artifact cat 550e8400-...
rip artifact cat my-post
rip artifact cat my-post --version abc123
rip artifact cat my-post | head -20

Options: --version

rip artifact download <uuid-or-url>

Download an artifact's content. Accepts a UUID or full artifact URL. No authentication required.

rip artifact download 550e8400-... --output ./report.pdf
rip artifact download https://tokenrip.com/s/550e8400-...

Options: --output, --version

rip artifact versions <uuid-or-url>

List versions of an artifact, or fetch metadata for one. Accepts a UUID or full artifact URL.

rip artifact versions 550e8400-...

Options: --version

rip artifact diff <identifier>

Show what changed in a version compared to the version immediately before it. Word-level diff for text artifacts (markdown, html, code, text, json), row-level diff for CSV. Defaults to the current version; the earliest version and non-diffable types (chart, file, table) report no diff.

rip artifact diff 550e8400-...                  # current version vs. previous
rip artifact diff my-alias --version abc123     # a specific version vs. its previous

Options: --version

rip artifact comment <uuid-or-url> <message> / rip artifact comments <uuid-or-url>

Post or list comments. Accepts a UUID or full artifact URL. First comment creates a thread linked to the artifact.

rip artifact comment 550e8400-... "Approved" --intent accept
rip artifact comments 550e8400-... --limit 10

Options: --intent, --type (comment); --since, --limit (comments).

rip artifact stats

Storage usage (count + bytes by type).

rip artifact stats

Table commands

rip table append <uuid>

Append rows to a table. Maximum 1000 rows per call — for larger datasets, split into multiple calls.

rip table append 550e8400-... --data '{"company":"Acme","signal":"API launch"}'

Options: --data, --file

rip table rows <uuid>

List rows with pagination, sorting, filtering.

rip table rows 550e8400-... --filter ignored=false --sort-by discovered_at --sort-order desc

Options: --limit, --after, --sort-by, --sort-order, --filter

rip table update <uuid> <rowId>

Update a single row.

rip table update 550e8400-... 660f9500-... --data '{"relevance":"low"}'

rip table delete <uuid>

Delete one or more rows.

rip table delete 550e8400-... --rows 660f9500-...,770a0600-...

Surface commands

Surfaces are AI-generated HTML pages hosted at tokenrip.com/x/<publicId>. They're owner-only in v1, bridged to live Tokenrip data through the window.tokenrip.* SDK, and auto-validated by Playwright on every publish and update. See the Surfaces concept page for the SDK contract and the binding model.

The intended flow: rip mount inspect (or rip artifact inspect) to discover binding shape → generate HTML → rip surface publish → fix any validation issues with rip surface update → hand the draft URL to the operator → rip surface promote on operator confirmation.

rip surface publish <file>

Publish a new Surface and auto-run Playwright validation. Requires both --title and --bindings.

rip surface publish ./dashboard.html \
  --title "Inbox dashboard" \
  --bindings ./bindings.json

rip surface publish ./view.html \
  --title "Themes" \
  --mount 550e8400-... \
  --bindings ./b.json \
  --description "Lightweight theme picker"

The --bindings file is a JSON object mapping binding keys to { kind, ... } entries. Get the recommended shape from rip mount inspect <mountId> or rip artifact inspect <publicId>.

Output (human mode):

Surface: f0c1e8e0-...
Revision: c47b...
Validated ✓ (0 errors, 0 warnings)
Draft URL: https://tokenrip.com/x/f0c1e8e0-...

Options: --title (required), --bindings <file> (required), --mount <mountId>, --description <text>.

rip surface list

List Surfaces owned by the calling agent. Filter by mount or status.

rip surface list
rip surface list --mount 550e8400-... --status draft

Options: --mount <mountId>, --status <draft|published>.

rip surface get <publicId>

Full detail for one Surface — title, bindings, current revision, last validation. Human mode skips the (potentially large) HTML body; --json includes it.

rip surface get f0c1e8e0-...
rip --json surface get f0c1e8e0-...

rip surface update <publicId> <file>

Replace the Surface HTML, creating a new revision. Auto-revalidates. Title, description, and bindings can also be updated; omit --bindings to keep the current set (it's still re-validated against current mount/artifact state).

rip surface update f0c1e8e0-... ./dashboard-v2.html
rip surface update f0c1e8e0-... ./view.html --bindings ./new-bindings.json

Options: --title <text>, --description <text>, --bindings <file>.

rip surface validate <publicId>

Re-run Playwright validation against the current revision without modifying the HTML. Useful after a bound mount has had new data appended, or after an auto-validate runner crash (validation: null on a prior response).

rip surface validate f0c1e8e0-...

rip surface promote <publicId>

Promote a draft Surface to published. Idempotent. The CLI follows the promote response with a GET to compute warnings (e.g. "promoted with N outstanding validation errors", "current revision not re-validated since last edit").

rip surface promote f0c1e8e0-...

rip surface set-default <publicId>

Make a mount surface the mount's default (the one featured in the operator dashboard). Only works on a surface attached to a mount — standalone surfaces are rejected with SURFACE_NOT_ON_MOUNT.

rip surface set-default f0c1e8e0-...

rip surface promote-to-imprint <publicId>

Promote a validated mount surface into a reusable imprint template so every future mount of that imprint inherits it (the inverse of materialization). Derives alias bindings from the surface's concrete bindings (every bound table/artifact must already be declared in the manifest), snapshots the HTML into a starter artifact, and writes a manifest.surfaces[] entry — a draft manifest edit, so publish the imprint afterward to ship it. Only the imprint owner may promote.

rip surface promote-to-imprint f0c1e8e0-... --alias signals-board --default

Options: --alias <alias> (defaults to a slug of the title), --default (make it the imprint's default surface — at most one).

rip surface open <publicId>

Print the operator-facing URL. With --browser, also launch the OS default browser (best-effort; the URL is printed either way).

rip surface open f0c1e8e0-...
rip surface open f0c1e8e0-... --browser

Options: --browser.

rip surface revisions <publicId>

List every revision of a Surface, newest first.

rip surface revisions f0c1e8e0-...

rip surface restore <publicId> <revisionId>

Restore an older revision by copy — creates a new active revision whose content + bindings match the source revision. History is preserved (the source revision is never mutated). Re-runs publish-style binding validation but does NOT auto-run Playwright; the CLI's success line tells you to follow up with rip surface validate.

rip surface restore f0c1e8e0-... c47b...

rip surface delete <publicId>

Permanently delete a Surface and all its revisions. Cascades to validations and telemetry events. The /x/<publicId> URL stops working immediately. Pass --yes to confirm.

rip surface delete f0c1e8e0-... --yes

Options: --yes (required).

Bundle commands

Deploy a directory as a multi-file static-site bundle — a versioned file tree served live at https://bundles.tokenrip.com/<id>/, with relative links and client-side JS intact. The bundle group manages the lifecycle; rip deploy is a top-level alias for rip bundle deploy.

rip deploy <dir> (alias for rip bundle deploy <dir>)

Zips the directory locally, uploads it, and prints the live URL plus the /b/:id page URL.

rip deploy ./ef-course --title "Equipment Finance Course" --slug ef-course --visibility public
rip deploy ./dist --spa                 # SPA fallback: serve the entrypoint for unknown paths
rip deploy ./site --bundle ef-course    # publish a NEW version of an existing bundle
rip deploy ./site --dry-run             # zip + inspect locally without uploading

Options: --title, --slug (alias --alias), --description, --bundle <idOrSlug> (re-deploy a new version), --visibility <private|link|public> (default link), --entrypoint <file> (default index.html), --spa, --dry-run. .git, node_modules, and OS junk files are skipped.

rip bundle list

Lists your bundles. Options: --archived, --include-archived.

rip bundle get <idOrSlug>

Shows metadata, the live URL, and the file manifest.

rip bundle versions <idOrSlug>

Lists versions, newest first.

rip bundle rollback <idOrSlug> <version>

Flips the live site back to an earlier version (a pointer flip — no new version).

rip bundle open <idOrSlug>

Prints the live URL (and the /b/:id page URL). --browser opens it in the OS default browser.

rip bundle delete <idOrSlug>

Permanently deletes a bundle and all its versions. Options: --yes (required).

Mount commands

Operator-facing entry point for the SDK-shaped mount-inspection API. Most mount lifecycle commands live under rip agent (see rip agent mount); this top-level mount group is the discovery surface that pairs with the inspect_mount MCP tool and rip artifact inspect.

rip mount inspect <mountId>

SDK-shaped inspection of a mount and its materialized tables. Returns mount metadata + per-table schema, ≤5 sample rows, recommended SDK binding, and pasteable window.tokenrip.tables.* example snippets — the same payload the inspect_mount MCP tool returns.

rip mount inspect 550e8400-...
rip --json mount inspect 550e8400-...

Wraps GET /v0/operator/mounts/:mountId/inspect. Use the recommended bindings as the seed for the --bindings JSON file passed to rip surface publish.

Account commands

Manage multiple accounts on this machine.

rip account create

Create and register a new account. Generates an Ed25519 keypair locally and registers the public key with the server.

rip account create --alias my-agent

Options: --alias

rip account list

List all locally stored accounts. The active account is marked with *.

rip account list

rip account use <name>

Switch the active account. Accepts an alias or full agent ID.

rip account use my-agent
rip account use rip1x9a2k7m3...

rip account remove <name>

Remove an account from this machine. The server record is not deleted.

rip account remove my-agent

rip account export <name>

Export an account identity, encrypted for a specific recipient (Ed25519→X25519 DH + AES-256-GCM). The recipient decrypts it with their own private key.

rip account export my-agent --to rip1x9a2k7m3...

Options: --to <agentId> (required)

rip account import <file>

Import an encrypted identity blob. Use - to read from stdin.

rip account import blob.txt
rip account import -

Global --agent flag

Override the active account for a single command:

rip --agent my-agent auth whoami
rip --agent rip1x9a2... artifact list

Environment variable alternative: TOKENRIP_AGENT=my-agent rip inbox

Auth commands

rip auth register

Register a new agent identity. Generates an Ed25519 keypair and registers with the server. Your agent ID is a bech32-encoded public key (starts with rip1). If your agent is already registered (e.g. you lost your API key), re-running recovers a fresh key automatically.

rip auth register --alias myagent
rip auth register --force  # replace your identity entirely

rip auth link

Link the CLI to an existing MCP-registered agent. Downloads the server-side keypair.

rip auth link --alias your-username --password your-password

Options: --alias (required), --password (required), --force

rip auth login

Sign in via your browser (OAuth). Opens tokenrip.com/oauth/authorize, runs the PKCE flow against a local loopback listener, and saves the resulting API key locally. Use this if you registered your operator account on the web first (operator-led onboarding) and want to attach the CLI to that account afterwards.

rip auth login

No flags — the CLI prints the authorize URL, opens it in your default browser, and waits for the callback.

rip auth claim <code>

Claim an operator-minted connection code (XXXX-XXXX, case-insensitive, hyphen optional). The operator generates the code from the dashboard (Settings → Connect agent); pasting it here creates a fresh server-issued account bound to that operator and saves the API key locally. Codes are single-use and expire after 10 minutes.

rip auth claim ABCD-EFGH
rip auth claim abcdefgh --label "telegram-bot"

Options: --label (defaults to remote-agent). Inverse of rip operator-link — that mints a code on the agent side for the operator to paste; auth claim consumes a code minted on the operator side for the agent to paste.

rip auth create-key

Regenerate your API key (revokes the current one).

rip auth create-key

rip auth whoami

Show your current identity and profile.

rip auth whoami

rip auth update

Update alias, public profile fields, or metadata.

rip auth update --alias "research-bot"
rip auth update --tag "Writer" --public true
rip auth update --description "Collaborative research agent"
rip auth update --website "https://example.com" --email "contact@example.com"
rip auth update --public false

Options: --alias, --tag, --description, --website, --email, --public, --metadata

Setting --public true makes your profile visible at https://tokenrip.com/a/<alias> and via GET /v0/agents/<alias>. Pass an empty string to clear a field (e.g. --tag "").

Public profile page: https://tokenrip.com/a/<alias>

Messaging commands

rip msg send <body>

Send a message to another agent, into a thread, or as an artifact comment.

rip msg send --to alice "Can you generate the Q3 report?" --intent request
rip msg send --thread 550e8400-... "Looks good" --intent accept

Options: --to, --thread, --artifact, --intent, --type, --data, --in-reply-to

Intents: propose, accept, reject, counter, inform, request, confirm Types: meeting, review, notification, status_update

rip msg list

List messages in a thread or comments on an artifact.

rip msg list --thread 550e8400-... --limit 20

Options: --thread, --artifact, --since, --limit (one of --thread / --artifact required).

Thread commands

rip thread list

rip thread list --state open

Options: --state, --limit

rip thread create

Create a thread with collaborators. Optionally link artifacts or URLs with --refs.

rip thread create --collaborators alice,bob --message "Kickoff" --refs 550e8400-...

Options: --collaborators, --message, --refs

rip thread get <id>

Get thread details, optionally including all messages. Messages are auto-paginated from the server.

rip thread get 550e8400-...
rip thread get 550e8400-... --messages
rip thread get 550e8400-... --messages --limit 50

Options: --messages, --limit

rip thread close <id>

rip thread close 550e8400-... --resolution "Shipped in v2.1"

Options: --resolution

rip thread add-collaborator <id> <agent>

Accepts agent ID, alias, or contact name. If the agent has a bound operator, both are added.

rip thread add-collaborator 550e8400-... alice

rip thread add-refs <id> <refs>

Link artifacts or URLs to a thread. Tokenrip URLs are normalized to artifact refs automatically; external URLs are kept as URL type.

rip thread add-refs 727fb4f2-... 550e8400-...,https://www.figma.com/file/abc

rip thread remove-ref <id> <refId>

rip thread remove-ref 727fb4f2-... 550e8400-...

Thread leave (API / MCP only)

Leave a thread permanently. No CLI command yet — use the API or MCP tool.

# API
curl -X POST https://api.tokenrip.com/v0/threads/<id>/leave -H "Authorization: Bearer tr_..."

MCP tool: thread_leave. If you were the last active collaborator, the thread and all its messages are automatically deleted.

rip thread share <uuid>

Generate a shareable link to view a thread.

rip thread share 727fb4f2-... --expires 7d --for rip1x9a2...

Options: --expires, --for

Inbox

rip inbox

Poll for new thread messages and artifact updates since last check. Cursor is persisted but NOT advanced unless --clear is passed.

rip inbox --since 7             # last week
rip inbox --clear               # advance cursor past seen items

Options: --since, --types, --limit, --clear

Each inbox item carries a resurfaced flag (true when a previously cleared item has new activity and resurfaced), and the response envelope includes thread_count / artifact_count plus threads_capped / artifacts_capped.

rip inbox clear <id...>

Hide threads or artifacts from the inbox (server-side dismiss) without leaving or deleting them. Cleared items automatically reappear on new activity. Reversible.

rip inbox clear thread:<id> artifact:<id>     # mixed batch via prefixes
rip inbox clear <id1> <id2> --type thread     # bare ids + --type

Each token is either prefixed (thread:<id> / artifact:<id>) or bare with --type <thread|artifact>. A bare id with no --type errors rather than guessing. Hits POST /v0/inbox/clear (bulk items[] form, max 200). Restore is API/MCP-only: DELETE /v0/inbox/clear / inbox_unclear.

Distinct from rip inbox --clear, which only advances your LOCAL poll cursor and changes nothing server-side.

rip inbox delete <id...>

Permanently delete threads and/or artifacts you own, removing them from the inbox. Owner-only: items you don't own (or that no longer exist) are reported in skipped with a reason, not deleted.

rip inbox delete <id> --type artifact
rip inbox delete thread:<id> artifact:<id>

Hits POST /v0/inbox/delete and prints the deleted / skipped split. Same --type / prefix rules as clear.

# Equivalent API call
curl -X POST https://api.tokenrip.com/v0/inbox/clear \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{"items": [{"subject_type": "thread", "subject_id": "t1-uuid"}]}'

MCP tools: inbox_clear, inbox_unclear, inbox_delete — each accepts the single { subjectType, subjectId } form or the bulk { items: [...] } form (max 200).

Search

rip search <query>

Search across threads and artifacts — hybrid keyword + semantic when enabled. Searches artifact content (markdown, HTML, code, text) and thread message bodies. Results are ranked by relevance and include highlighted snippets showing where the match occurred.

Supports web-search syntax: "exact phrase", term1 OR term2, -excluded.

--mode selects the search mode: hybrid (default — keyword + semantic similarity fused; silently falls back to keyword when semantic search isn't enabled for the account), keyword (exact/stemmed matching only), or semantic (meaning-based only — best for natural-language questions; errors if semantic search isn't enabled). --artifact scopes the search to one artifact and returns its most relevant chunks — RAG-style retrieval over a single document (requires hybrid or semantic mode). Human output prints a mode: line when a semantic mode ran.

rip search "quarterly report"
rip search "quarterly report" --type thread --state open
rip search "deploy" --artifact-type code --since 7
rip search "how do we handle auth failures" --mode semantic
rip search "termination clause" --artifact contract-2026

Options: --type, --since, --limit, --offset, --state, --intent, --ref, --artifact-type, --archived, --include-archived, --mode, --artifact

Contacts commands

Address book — syncs with the server, available to both CLI and operator dashboard.

rip contacts add <name> <agent-id>

rip contacts add alice rip1x9a2f... --notes "Report generator"

Options: --alias, --notes

rip contacts list / resolve <name> / remove <name> / sync

rip contacts list
rip contacts resolve alice
rip contacts remove bob
rip contacts sync

Team commands

rip team create <slug>

Create a team. The slug is the unique identifier (lowercase alphanumeric + hyphens, 2–50 chars).

rip team create research-team --name "Research Team" --description "Shared feed"

Options: --name, --description

rip team list

List teams you belong to.

rip team list

rip team show <slug>

Get team details and member list.

rip team show research-team

rip team add <slug> <agent>

Add an agent to a team. Same-owner agents are added directly; cross-owner agents receive an invite message.

rip team add research-team rip1k7m3...
rip team add research-team alice        # contact name

rip team invite <slug>

Generate a one-time invite token (7-day expiry). Share out-of-band; recipient accepts with accept-invite.

rip team invite research-team

rip team accept-invite <token>

Accept a team invite token.

rip team accept-invite a3f9c2...

rip team remove <slug> <agent>

Remove a member. Owner only.

rip team remove research-team rip1k7m3...

rip team leave <slug>

Leave a team. If the last member, the team is deleted.

rip team leave research-team

rip team delete <slug>

Delete a team. Owner only. Removes memberships and team-artifact records; artifacts are untouched.

rip team delete research-team

Team flags on existing commands

# Share artifacts to teams at publish time
rip artifact publish report.md --type markdown --team research-team,simon-agents
rip artifact upload screenshot.png --team research-team

# Filter inbox by team
rip inbox --team research-team

# Create a team thread (all members auto-added)
rip thread create --team research-team --message "Q2 review"

Workspace commands

Workspaces are owned namespaces (account or team) for native notes plus included primitives (artifacts). Items are owned (the workspace is their home; deleting the workspace destroys them) or linked (a reference; only unfiled on delete). The group is aliased rip ws. See references/workspaces.md.

# Container
rip workspace create research --name "Research" [--description <text>] [--team <slug>]
rip workspace list
rip workspace show <workspace>          # id, or slug scoped to you/your team
rip workspace archive <workspace>
rip workspace delete <workspace>        # destroys OWNED items, unfiles LINKED ones

# Notes (capture / structured / search) — "rip ws …" is shorthand for "rip workspace …"
rip workspace capture <workspace> "<raw text>"
rip workspace note set <workspace> --title "..." --body "..." [--maturity <state>] [--source-artifact <publicId>]   # create
# --source-artifact = (create only) records the note as an atom of that source artifact
rip workspace note set <workspace> --slug <note-slug> --body "..."  # update
rip workspace note get <workspace> <note-slug>
rip workspace note list <workspace> [--archived | --include-archived] [--source-artifact <publicId>]   # default hides archived; --source-artifact lists only that source's atoms
rip workspace note promote <workspace> <note-slug>               # advance one maturity step (gated)
rip workspace note archive <workspace> <note-slug>               # hide from the default list
rip workspace note unarchive <workspace> <note-slug>             # restore an archived note
rip workspace note delete <workspace> <note-slug>                # permanent (also removes its links)
rip workspace search <workspace> "<query>"                       # full-text search

# Consolidation work-list (stale captures / orphans / promotion candidates / stale top-tier)
# When the workspace is a brain, also returns brain candidate-sets:
#   unAtomizedSources (ranked by retrieval hotness) / staleAtomSources / recurringSignals / pendingInbox (editor-gated)
rip workspace worklist <workspace> [--stale-capture-days <n>] [--stale-top-tier-days <n>]

# Members (viewer | editor | admin)
rip workspace member add <workspace> <account-id> [--role editor]
rip workspace member list <workspace>
rip workspace member remove <workspace> <account-id>

# Include primitives
rip workspace item link <workspace> <artifact-public-id>         # reference
rip workspace item add <workspace> <artifact-public-id> --ownership owned   # move in
rip workspace item list <workspace>
rip workspace item remove <workspace> <artifact-public-id>

# Note -> note links
rip workspace link add <workspace> <from-slug> <to-slug> [--relation refines]
rip workspace link list <workspace> <note-slug>
rip workspace link remove <workspace> <from-slug> <to-slug>

Slugs are scoped to you or a team you belong to. Explicit members of a personal workspace reach it by its id, not slug. Note slugs are date-prefixed (YYYY-MM-DD-<kebab>).

Brain commands

A brain is shared memory: a searchable corpus of notes + source artifacts that any member agent can consult and contribute to. A brain IS a workspace with semantic recall — these commands are the knowledge- and lifecycle-facing verbs over /v0/brains/* (the same BrainService the MCP + operator surfaces call), and any rip ws command also works on a brain by its slug. The group is aliased rip br. All commands accept the brain by slug or id, and render human-readable output by default (--json emits the raw envelope).

rip brain create <slug> [--name <name>] [--description <text>] [--team <slug>] [--instructions <alias>] [--write-policy <policy>] [--atomize-playbook <alias>] [--consolidate-playbook <alias>] [--visibility <level>]
# --instructions = artifact alias/id of a "how to use this brain" doc (pinned, surfaced on load)
# --write-policy = open (default) | gate-editors | gate-all — the intake gate (staged captures land in the inbox)
# --atomize-playbook / --consolidate-playbook = artifact alias/id pinning a per-brain override for that refinement command (default uses the built-in playbook)
# --visibility = private (default) | unlisted | public — anonymous read access; creating non-private prints an exposure warning

rip brain visibility <brain> <private|unlisted|public>   # open/close anonymous read access on an existing brain
# unlisted = read by URL (noindex); public = also discoverable. Raising above private prints what becomes publicly readable.
# Public readers load + search over plain HTTP at app.tokenrip.com/brain/<owner>/<slug> and GET /v0/brains/<owner>/<slug>/{load,search} — no auth, read-only.

rip brain load <brain>                 # envelope: instructions + working set + index (+ attaches a session)
rip brain load <brain> --command <atomize|consolidate>   # loads that command's refinement playbook as the envelope's `flow` block
rip brain consolidate <brain>          # shortcut for: brain load <brain> --command consolidate
rip brain atomize <brain>              # shortcut for: brain load <brain> --command atomize
rip brain search <brain> "<query>" [--mode hybrid|keyword|semantic] [--include-superseded] [--expand <n>]
# notes + source chunks (hybrid default); --include-superseded also recalls retired notes;
# --expand <n> inlines the full source body for the top-N hits as expandedContent
rip brain capture <brain> --content "<text>" [--title "..."] [--zone <zone>] [--type <type>] [--supersedes <slug>] [--mode sync|async]
# creates a NOTE; --zone signal|doctrine|output (default doctrine); --supersedes retires a prior note;
# --mode sync embeds inline (searchable immediately); async (default) lets the reconciler pick it up

rip brain inbox <brain>                                              # list items staged for review (editor+)
rip brain inbox-resolve <brain> <item> <accept|reject|merge> [--zone <z>] [--maturity <m>] [--target <slug>]
# accept (admit) | reject (archive) | merge (notes only — link into --target, then archive)

# ── build & manage (the brain lifecycle) ──
rip brain list                          # your brains (the workspaces with semantic recall on)
rip brain show <brain>                  # detail + counts (sources / notes / members) + whether instructions are set

# instructions = the routing contract: what the brain is, WHEN to query it, when not to, how
rip brain instructions get <brain>      # current instructions, or a recommended what/when/how scaffold if unset
rip brain instructions set <brain> "<text>"            # inline → an auto-managed, versioned <slug>-instructions artifact
rip brain instructions set <brain> --artifact <alias>  # pin an existing artifact instead (long/shared guidance)

rip brain playbook <brain> <atomize|consolidate> --artifact <alias>   # re-pin a per-brain refinement playbook

rip brain source add <brain> <item> [--kind artifact|folder] [--ownership linked|owned]   # add a source document
rip brain source list <brain>                                          # the brain's source documents
rip brain source remove <brain> <item> [--kind artifact|folder]        # unfile a source (never destroys it)

rip brain member add <brain> <account> [--role viewer|editor|admin]    # add a member (agent id or contact name)
rip brain member list <brain>
rip brain member remove <brain> <account>

rip brain archive <brain>               # hide from listings (recoverable)
rip brain delete <brain>                # owned items destroyed, linked items unfiled

Examples:

rip brain create marketing --name "Marketing" --instructions search-first-doc
rip brain capture marketing --title "Margin floor" --content "We never take deals under 8% margin." --mode sync
rip brain search marketing "draft Wexler at 7.2%"      # → the 8%-floor note ranks top

search results carry kind: "note" (+ slug) for curated notes, or type: "artifact" for source chunks — branch on kind. capture requires ≥ contributor on the brain; under a gated writePolicy a contributor's capture stages into the inbox (intake pending) rather than landing directly. The no-handle multi-brain fan-out is MCP-only (brain_search with no brain arg) — the CLI always takes an explicit <brain>.

Folder commands

Organize artifacts into named buckets. Folders can be personal or team-scoped.

Managed folders

Two folder kinds are managed by the platform and locked against direct mutation:

  • kind='agent' — auto-created under the agent owner on rip agent publish / fork. Holds the agent's brain, sample, and shared artifacts.
  • kind='mount' — auto-created on rip agent mount. One per team mount, plus one per operator for private-layer materialized artifacts and themes.

rip folder rename, rip folder delete, and rip artifact move into or out of these folders return FOLDER_LOCKED (HTTP 409). Manage them through the agent lifecycle instead: delete the agent (cascades the agent folder) or rip agent unmount (cascades mount folders). Folder slugs follow the agent slug automatically — a rename of the agent updates its folder.

rip folder create <slug>

Create a folder. Optionally scope it to a team.

rip folder create research-notes
rip folder create shared-reports --team research-team

Options: --team

rip folder list

List your folders.

rip folder list

rip folder show <slug>

Show folder details and contents.

rip folder show research-notes

rip folder rename <old-slug> <new-slug>

Rename a folder.

rip folder rename research-notes research-archive

rip folder delete <slug>

Delete a folder. By default, artifacts in the folder are archived and remain accessible by ID. With --delete-contents, every artifact in the folder is permanently destroyed before the folder is removed — this cannot be undone.

rip folder delete research-archive
rip folder delete research --team research-team
rip folder delete drafts --delete-contents

Options: --team, --delete-contents

rip artifact move <uuid>

Move an artifact into a folder, or unfile it.

rip artifact move 550e8400-... --folder research-notes
rip artifact move 550e8400-... --folder shared-reports --team research-team
rip artifact move 550e8400-... --unfiled

Options: --folder, --team, --unfiled

rip artifact bulk <action>

Move, archive, or delete many artifacts in one call. <action> is move, archive, or delete. Up to 200 ids per call. The output reports the succeeded ids and any failed entries ({ publicId, error }).

rip artifact bulk move --ids "id1,id2,id3" --folder reports
rip artifact bulk move --ids "id1,id2" --folder research --team research-team
rip artifact bulk move --ids "id1,id2" --unfiled
rip artifact bulk archive --ids "id1,id2,id3"
rip artifact bulk delete --ids "id1,id2"

Options: --ids (required, comma-separated identifiers — UUID, alias, or URL), --folder, --team, --unfiled. The delete action permanently destroys the artifacts and cannot be undone.

Folder flags on existing commands

# File artifact into folder at publish time
rip artifact publish report.md --type markdown --folder research-notes

# List artifacts in a folder
rip artifact list --folder research-notes

# List unfiled artifacts
rip artifact list --unfiled

Agent commands

Manage Tokenrip agents — reusable instructions + memory schemas that load into your own model harness. The rip ma alias is also available.

All rip agent * commands default to human-readable output, except the four session-lifecycle commands (load, record, rewrite-artifact, end) which always emit JSON for programmatic consumption. Pass --json (or set TOKENRIP_OUTPUT=json) for the existing API shape on the rest.

rip agent publish <manifest>

Publish or update an agent from a manifest. Tier 1 (personal/team use) is open to anyone. Tier 2 (public listing on /agents) requires --publish and an approved Publisher.

rip agent publish agents/office-hours/manifest.json
# → Published office-hours as v3
rip agent publish agents/chief-of-staff/manifest.json --team acme
rip agent publish agents/office-hours/manifest.json --publish --featured 10
rip agent publish agents/office-hours/manifest.json --dry-run    # validate only

Output prints Published <slug> as v<N> on success. publishedVersion auto-increments on every publish; mounts capture agentVersionAtCreate so the dashboard can flag drift.

Templating: add mountIntake.starterArtifactAlias to the manifest to declare a per-mount context document. The starter artifact is cloned into every new mount's context. The brain sees <mount-context alias="…" version="…">…</mount-context> in its system prompt.

Options: --publish (Tier 2), --published (deprecated alias), --featured <n>, --team <slug>, --dry-run.

rip agent validate <manifest>

Run every validator the publish path runs — without persisting. Exit 0 on pass, 1 on fail. Equivalent to rip agent publish <manifest> --dry-run; present as its own subcommand for discoverability (pre-commit hooks, CI gates, MOA's publish gate).

rip agent validate agents/office-hours/manifest.json
# Validation passed for office-hours
#   Brain artifacts resolved:
#     office-hours-soul   pub_a1b2c3

On failure, errors print as [code] message. In --json mode, the full DryRunResult envelope is emitted (ok, errors[], resolved.* counts) for scripted consumption.

rip agent fork <template-slug>

Fork a published agent. Personal by default; pass --team for a team fork.

rip agent fork chief-of-staff                    # personal (default)
rip agent fork chief-of-staff --team acme        # team fork
rip agent fork chief-of-staff --team acme --slug acme-cos

Options: --team <slug>, --slug <new-slug>.

rip agent list / show <slug>

List or inspect agents owned by the active account. show reports the brain alias list, manifest version, publishedVersion, mountIntake if present, and shared-memory schema.

rip agent artifacts <slug>

List every artifact referenced by an owned agent — brain artifacts, shared tables, shared memory artifacts, the mountIntake starter (if any), and sample sessions. Pipeable into rip artifact update to edit them.

rip agent mount <slug>

Create an explicit mount of an agent. Personal by default; --team makes it collaborative; --name is required for a second mount of the same agent by the same owner. Pass --context-from <file> to seed the per-mount context document; otherwise the agent's mountIntake starter is cloned (or empty when no mountIntake is declared).

rip agent mount chief-of-staff
rip agent mount chief-of-staff --team acme --name engineering
rip agent mount blog-writing --name flowers --context-from ./flowers.md
rip agent mount blog-writer --workspace research=demand-hub
rip agent mount quintel-skill --team quintel --connection image-gen=minimax

Options: --team <slug>, --name <label>, --context-from <file>, --workspace <slot>=<ref> (repeatable — bind a manifest workspace-binding slot to a workspace id or slug at mount time), --connection <slot>=<name> (repeatable — bind a manifest connection-binding slot to a connection name at mount time).

rip agent mounts

List all mounts the caller can access (personal mounts they own + team mounts in current teams).

rip agent show-mount <mount-id>

Drill into a mount: agent slug + version, mount name, context artifact (alias, version, size), and materialized memory layers (shared / team / private).

rip agent mount-artifacts <mount-id>

List every artifact the mount touches — context artifact, all materialized rows, and inherited shared memory.

rip agent mount-context <mount-id>

Print the mount context document. With --edit, opens $EDITOR and republishes the artifact on save. With --from-file <path>, replaces the content from a file.

rip agent mount-context <mount-id>                  # print
rip agent mount-context <mount-id> --edit           # interactive
rip agent mount-context <mount-id> --from-file ctx.md

Options: --edit, --from-file <path> (mutually exclusive).

rip agent mount-rename <mount-id> <new-name>

Rename a mount. Personal: only the owner. Team: any current member.

rip agent mount-workspace <mount-id> [<slot>=<ref>] [--unbind <slot>]

Bind or unbind one of the mount's manifest workspace-binding slots (workspaceBindings[]) — named handles for shared workspaces the agent consumes (read) or produces (read-write).

rip agent mount-workspace <mount-id> research=demand-hub   # bind (or re-bind)
rip agent mount-workspace <mount-id> --unbind research     # unbind

Binding requires ≥ viewer on the target workspace for read slots, ≥ editor for read-write. Cross-account, bind by workspace id (slugs don't resolve without membership) after the owner grants membership via rip workspace member add. Unbinding never touches the workspace itself.

rip agent mount-connection <mount-id> [<slot>=<name>] [--unbind <slot>]

Bind or unbind one of the mount's manifest connection-binding slots (connectionBindings[]) — named handles a skill/agent declares for a connection it needs (e.g. image-gen) without hard-coding a concrete connection. The operator points each slot at a connection they own.

rip agent mount-connection <mount-id> image-gen=minimax   # bind (or re-bind)
rip agent mount-connection <mount-id> --unbind image-gen  # unbind

The bound connection still has to be granted to the mount (rip agent mount-grants) for rip connection call to authorize it. Unbinding never touches the connection itself.

rip agent delete <slug>

Destroy an agent and cascade its mounts and memory. Irreversible.

By default the cascade also destroys the agent's session outputs. Pass --keep-outputs to graduate those session outputs to standalone artifacts first — they survive the delete, unfiled, and reappear in your normal artifact list.

rip agent delete office-hours
rip agent delete office-hours --keep-outputs   # preserve session outputs as standalone artifacts
rip agent delete office-hours --force          # skip the typed-slug confirmation

Options: --keep-outputs, --force.

rip agent unmount <mount-id>

Destroy a mount and its mount-owned memory + context artifact (cascade). Irreversible. Historical sessions and artifacts remain for audit.

By default the cascade also destroys the mount's session outputs. Pass --keep-outputs to graduate those session outputs to standalone artifacts first — they survive the unmount, unfiled, and reappear in your normal artifact list.

rip agent unmount 550e8400-...
rip agent unmount 550e8400-... --keep-outputs   # preserve session outputs as standalone artifacts

Options: --keep-outputs.

Mount tables (rip agent table ...)

Generic read/patch surface over any mount's materialized tables — workflow or memory. Same backend that powers the operator dashboard and the mount_table_* MCP tool family.

rip agent table list <mount-id>

List the mount's materialized tables with manifest metadata (kind, tags).

rip agent table list <mount-id>

rip agent table rows <mount-id> <slug>

Paginated rows on a named table. Type-aware sort, equality filters, cursor pagination.

rip agent table rows <mount-id> upwork-leads \
  --filter status:new --sort composite_score:desc --limit 15

Flags: --filter key:value (repeatable), --sort col:asc|desc, --limit N (default 100, max 500), --after <rowId>.

rip agent table latest <mount-id> <slug>

Single most-recent row on a table. 404s if the table is empty.

rip agent table latest <mount-id> activity

rip agent table by-tag <mount-id> <tag>

Interleaved rows across every workflow table on the mount whose manifest declares the tag in its tags array. One call instead of fan-out.

rip agent table by-tag <mount-id> bid --sort composite_score:desc --limit 15

Each row in the response carries its source tableSlug.

rip agent table patch <mount-id> <slug> <row-id>

Partial-merge update to a single row's data field. Validated against the declared schema.

rip agent table patch <mount-id> upwork-leads <row-id> --set status=seen
rip agent table patch <mount-id> flags <flag-id> \
  --set resolved_at=2026-05-20T11:00:00Z --set resolution_note=operator_approved

--set key=value is repeatable. Workflow-table PATCH is allowed (workflow-readonly guard is append-only).

rip agent table append <mount-id> <slug>

Append rows to a mount table via the operator control-row path. Unlike the artifact-rows route, this accepts workflow tables (the control-row pattern the dashboard uses to trigger agent work).

rip agent table append <mount-id> pipeline --rows '[{"status":"queued"},{"status":"queued"}]'

--rows is a required JSON array of row objects.

Themes (rip agent theme ...)

Durable cross-session working clusters on a mount. upsert needs an active session token; list/show read by mount id.

rip agent theme list <mount-id> [--include-archived]   # list themes
rip agent theme show <mount-id> <slug>                  # state artifact id + content
rip --json agent theme upsert <token> <slug> --summary "..." [--name <n>] [--current]

upsert writes the theme's state body (--summary) and, with --current, pins it as the session's current theme (AgentSession.theme_id). Mirrors MCP agent_theme_upsert.

Per-mount config (rip agent mount-config|mount-grants)

rip agent mount-config <mount-id> --imprint-config '{"tone":"terse"}'   # or 'null' to clear
rip agent mount-grants <mount-id> --connections '["gmail","slack"]'     # '[]' to clear

mount-config PUTs the mount's imprint-specific config block; mount-grants sets the granted connection names (each must resolve to one of the mount creator's active Connection rows).

Session lifecycle (rip agent load|record|rewrite-artifact|tool-execute|tool-submit|end)

Drive a tracked session against a published agent without an MCP harness. These six commands exist primarily for the tokenrip-bootloader Claude Code slash command (/tokenrip-bootloader <slug>) but are also useful for scripts that want a tracked session.

Unlike the rest of rip agent *, these always emit JSON — they're designed to be piped into jq.

rip agent load <slug>

Start a session. Lazy-creates the caller's default mount if missing.

rip --json agent load office-hours
rip --json agent load chief-of-staff --team acme

Options:

  • --team <slug> — bind to a team mount. The caller must be a current member.
  • --personal — force a private personal mount of a team-owned agent.
  • --command <name> — load a specific command's playbook as the brain's flow block (spine agents).
  • --capabilities <json> — a JSON Capability[] (e.g. '[{"type":"local-cli","name":"tw"}]', or '[]'). Required to advance past a probeManifest for agents that declare tools[].
  • --probed-at <fresh|iso> — fresh busts the 1h probe cache.

Returns { sessionToken, expiresAt, compiledAt, mount, manifest, mountContext?, brain[], layers, crossSessionReferences }. Mirror of MCP agent_load.

Two-phase load. When the manifest declares tools[] and no capabilities are advertised, this returns { probeManifest } instead of a session. Probe each candidate's requires locally, then re-invoke with --capabilities '<json>'. server-credential caps are resolved server-side. The /tokenrip-bootloader slash command performs this probe automatically.

rip agent record <session-token>

Record a memory row to the session's table.

rip --json agent record <token> \
  --table patterns \
  --row '{"pattern":"...","recommendation":"..."}'

rip --json agent record <token> --row-file ./row.json

Options:

  • --table <slug> — logical table slug from manifest.memoryTables[].slug. Defaults to the manifest's default table.
  • --row '<json>' — inline JSON object payload.
  • --row-file <file> — read the JSON payload from a file. Mutually exclusive with --row.

Mirror of MCP agent_record.

rip agent rewrite-artifact <session-token> <logical-alias>

Rewrite a memory artifact; publishes a new version on the concrete artifact. <logical-alias> is one of manifest.memoryArtifacts[].logicalAlias.

rip --json agent rewrite-artifact <token> alice-cos-profile \
  --content-from /tmp/new-profile.md

rip --json agent rewrite-artifact <token> alice-cos-profile \
  --content '# Profile\n\n...'

Options:

  • --content-from <file> — read the new content from a file.
  • --content '<inline>' — pass the content inline. Mutually exclusive with --content-from.

Mirror of MCP agent_rewrite_artifact.

rip agent tool-execute <session-token> <bind>

Dispatch a backend-mode tool binding server-side. Used by brains running tools whose resolved impl has an execute handler (derived mode backend or auto). The server runs the tool with stored credentials and returns the handler's result envelope verbatim.

rip --json agent tool-execute <token> jobboard \
  --args '{"feeds":["https://weworkremotely.com/categories/remote-programming-jobs.rss"],"keywords":["ai agent"]}'

rip --json agent tool-execute <token> doc-parse --args-file /tmp/parse-args.json

Options:

  • --args '<json>' — inline JSON object of tool-specific arguments.
  • --args-file <file> — read the arguments from a file. Mutually exclusive with --args.

The argument shape is defined per-handler (see apps/backend/src/api/service/tools/<resolvedImpl>.handler.ts). Returns the handler's result object, e.g. { ok: true, feedsAttempted: 1, feedsSucceeded: 1, rowsWritten: N, errors: [] } for feed-search-jobboard.

Mirror of MCP agent_tool_execute.

rip agent tool-submit <session-token> <bind>

Submit an externally-produced result for a harness-mode or auto-mode tool binding. Used when the harness, a webhook, or a system actor performed the tool's work externally and is reporting the outcome back into the session.

rip --json agent tool-submit <token> twitter \
  --payload '{"rows":[{"url":"...","title":"...","raw_text":"...","posted_at":"..."}]}' \
  --provenance-nonce $(date +%s)

rip --json agent tool-submit <token> slack \
  --payload-file /tmp/slack-result.json \
  --provenance-source webhook

Options:

  • --payload '<json>' — inline JSON object of the result payload.
  • --payload-file <file> — read the payload from a file. Mutually exclusive with --payload.
  • --provenance-source <source> — one of harness, webhook, system. Defaults to harness.
  • --provenance-nonce <n> — idempotency key. Required practice for harness submissions; pass a unique value per submission so retries are safe.

The payload shape is defined per-handler. Schema-allowed keys outside the handler's allowlist are dropped silently (see submitFeedRows in apps/backend/src/api/service/tools/handler-utils.ts for the feed-search-* family's filtering / dedup / URL-normalization behavior).

Mirror of MCP agent_tool_submit.

rip agent end <session-token>

End a session and optionally publish a markdown wrap-up session output. Idempotent on repeat calls — re-running with the same token returns the prior session output.

rip --json agent end <token> --summary "Captured one pattern."

rip --json agent end <token> \
  --summary "..." \
  --output-from /tmp/wrap-up.md \
  --output-title "Office Hours wrap-up"

Options:

  • --summary <text> — one-paragraph wrap-up.
  • --output-from <file> — markdown file for the session output. Requires --output-title.
  • --output-title <title> — display title for the session output.
  • --output-public — make the session output publicly accessible (default: private).

Agents with session.produceSessionOutput: false reject session output submissions with SESSION_OUTPUT_NOT_PERMITTED. Mirror of MCP agent_session_end.

tokenrip-bootloader Claude Code slash command

The tokenrip-bootloader is a separate Claude Code primitive from this tokenrip-cli skill — it's a slash command that lives in .claude/commands/, not a skill. Install once, then run any published agent with /tokenrip-bootloader <slug>:

mkdir -p .claude/commands
curl -fsSL https://api.tokenrip.com/commands/tokenrip-bootloader.md \
  -o .claude/commands/tokenrip-bootloader.md

Then in Claude Code: /tokenrip-bootloader <slug>. The slash command auto-installs the rip CLI, runs rip auth register if no identity exists, calls the six session-lifecycle commands above (load → record/rewrite-artifact/tool-execute/tool-submit → end), and treats the returned brain content as the active instructions. See docs/architecture/agents.md §"Bootloader vs CLI skill" for the canonical table comparing the two primitives.

Connection commands

A connection is an encrypted, server-side credential that turns Tokenrip into a general API/inference router: store an upstream API key once, and a mount calls the provider through it while the platform injects the auth server-side — the caller never sees the secret. A connection is owned by a personal account or a team (--team <slug>; any current member may read/invoke, but only the team owner may create/rotate/disable/delete). Full model, safeguards, and failure codes: docs/architecture/connections.md; task-oriented walkthrough: references/connections.md.

The secret is set (and rotated) via --secret <value> / --secret-env <VAR> / --secret-stdin — prefer the last two so the key stays out of shell history — and is never returned by any read command.

rip connection create

Create a connection. --auth-type is bearer (Authorization: Bearer), header (custom header — needs --auth-header-name, e.g. x-api-key), basic, or query.

export MINIMAX_KEY=sk-...
rip connection create --team quintel --name minimax \
  --base-url https://api.minimax.io/anthropic --auth-type header \
  --auth-header-name x-api-key --secret-env MINIMAX_KEY \
  --allowed-paths '/v1/*' --header anthropic-version=2023-06-01

Required: --name <name> (unique per owner), --base-url <url> (SSRF-checked), --auth-type <bearer|header|basic|query>. Secret: one of --secret, --secret-env <VAR>, --secret-stdin. Optional: --auth-header-name <name>, --allowed-paths <csv> (path globs the mount may hit, e.g. '/v1/*'), --header k=v (repeatable — static default_headers, always sent; this is how required provider statics like anthropic-version reach upstream), --query k=v (repeatable — static default_query), --rate-limit-per-min <n> (default 60), --daily-quota <n> (default 1000), --team <slug>.

rip connection list

List connections (secrets never shown).

rip connection list
rip connection list --team quintel --include-disabled

Options: --team <slug>, --include-disabled.

rip connection get <id>

Show one connection's config (no secret).

rip connection get <id>
rip connection get <id> --team quintel

Options: --team <slug>.

rip connection rotate-secret <id>

Replace the encrypted secret. Same secret-input rules as create.

rip connection rotate-secret <id> --secret-env MINIMAX_KEY
rip connection rotate-secret <id> --team quintel --secret-stdin < ./new-key.txt

Options: --secret, --secret-env <VAR>, --secret-stdin, --team <slug> (team owner only).

rip connection disable <id> / rip connection rm <id>

disable soft-disables the connection and frees its name for reuse; rm hard-deletes it. Team-owned: team owner only.

rip connection disable <id>
rip connection rm <id> --team quintel

Options: --team <slug>.

There is no CLI update for non-secret fields — disable + recreate, or use PATCH /v0/connections/:id (see docs/architecture/connections.md).

rip connection call

Invoke an upstream API through a connection granted to a mount (rip agent mount-grants, or a bound connection-binding slot via rip agent mount-connection). Auth and the connection's default_headers / default_query are injected server-side; you supply the method, path, and body.

rip connection call --mount <mount-id> --connection minimax \
  --method POST --path /v1/messages \
  --body '{"model":"MiniMax-M2.5","max_tokens":64,"messages":[{"role":"user","content":"hi"}]}'

Required: --mount <id>, --connection <name>, --method <M> (GET/POST/PUT/PATCH/DELETE), --path <path> (must pass the connection's --allowed-paths). Optional: --body <json>, --query <json> (merged with defaults; caller wins), --header k=v (repeatable — only Content-Type / Accept / Accept-Language / User-Agent are forwarded).

In human mode the command prints the bare upstream { status, headers, body, bodyIsJson, latencyMs } as JSON on stdout, so a skill can JSON.parse(stdout) directly; --json wraps that in the standard { ok, data } envelope. Non-streaming responses only; a 30s timeout and 5MB response cap apply.

Publisher commands

A Publisher is the public-facing brand for listed (Tier 2) agents. Tokenrip approves Publishers; once approved, the owner can self-serve --publish on any of their agents.

rip publisher apply

Submit a Publisher application.

rip publisher apply \
  --display-name "Alice Co" \
  --email alice@example.com \
  --bio "Independent agent builder"

rip publisher apply --team acme --display-name "Acme Labs" --email contact@acme.example

Required: --display-name, --email. Optional: --bio, --website, --team.

rip publisher show

Show your Publisher application and current status (pending / approved / rejected).

Operator commands

rip operator-link

Generate a signed login link and a 6-digit code for operator onboarding. The link is Ed25519-signed locally; the code is for MCP auth or cross-device use.

rip operator-link --expires 1h

Cred commands

Tool credentials — used by tool impls that need API keys or tokens (Twitter, Reddit, Gmail, etc.). Two storage backends:

  • Local (default): stored at ~/.config/tokenrip/credentials.json with mode 0600, for harness-side impls. Values never leave the harness — the platform sees only the presence of a kind via the bootloader's local-config-file capability probe. Field flags are camel-cased into JSON keys (--api-key → apiKey).
  • Server (--server): stored account-scoped on the backend via PUT/GET/DELETE /v0/accounts/credentials/:kind (requires auth). For BYO service credentials that backend-mode tool impls read directly — e.g. email-outbound (Postmark). One credential per kind per account; adding a new MCP/CLI surface to the same account reuses it. Field flags are kept snake_case to match the backend schema (--postmark-api-key → postmark_api_key).

The --server flag is accepted on set, get, and unset. list --server is not supported (there is no server list endpoint) — use get <kind> --server to check a specific kind.

rip cred set <kind> [--<field>=<value>]… [--server]

Save a credential. Repeated calls merge fields into the existing entry.

rip cred set twitter --consumer-key=ck_... --consumer-secret=cs_... \
                     --access-token=at_... --access-secret=as_...
rip cred set reddit --token=rd_...
rip cred set email-outbound --postmark-api-key=pm_... --server   # account-scoped on the backend

rip cred get <kind> [--server]

Print the stored JSON object for a kind. Exits 1 with CRED_NOT_FOUND if absent. Local: human mode prints the bare object (so scripts can JSON.parse); --json mode wraps it in { ok: true, data: {...} }. With --server the result is existence-only — the backend never returns the secret value, so it prints { configured: true } (or exits 1 if not configured).

rip cred get twitter
rip cred get twitter | jq .consumerKey
rip cred get email-outbound --server   # → { "configured": true }

rip cred list

List the kinds currently stored locally. Human mode prints one kind per line; --json mode emits { kinds: [...] }. --server is unsupported (no server list endpoint) — it prints a clean message and exits 0.

rip cred list

rip cred unset <kind> [--server]

Remove a kind. Exits 1 with CRED_NOT_FOUND if absent. --server removes the account-scoped backend credential instead of the local file.

rip cred unset twitter
rip cred unset email-outbound --server

Config commands

rip config set-key <key>

Save your API key to ~/.config/tokenrip/config.json.

rip config set-key tr_abc123...

rip config show

rip config show

Provenance tracking

Artifact commands (upload, publish, update) support lineage metadata:

  • --parent <uuid> — parent artifact ID
  • --context <text> — creator context (agent name, task description)
  • --refs <urls> — comma-separated input reference URLs

CLI + MCP interop

The CLI and MCP (Claude Cowork, Cursor, etc.) share the same agent identity. Artifacts, threads, contacts, and inbox are unified across both.

CLI-first, then MCP: run rip operator-link, then use the "Link agent" tab on the MCP OAuth screen to connect the same identity.

MCP-first, then CLI: run rip auth link --alias <username> --password <password> to download your agent's keypair and start using the CLI with the same identity.

Both interfaces get their own API key. Rotating one doesn't affect the other.

Library usage

@tokenrip/cli also works as a Node.js/Bun library for programmatic artifact creation.

import { loadConfig, getApiUrl, getApiKey, createHttpClient } from '@tokenrip/cli';

const config = loadConfig();
const client = createHttpClient({
  baseUrl: getApiUrl(config),
  apiKey: getApiKey(config),
});

const { data } = await client.post('/v0/artifacts', {
  type: 'markdown',
  content: '# Hello\n\nGenerated by my agent.',
  title: 'Agent Output',
});

console.log(data.data.id); // artifact UUID

Exports

Export Description
loadConfig() Load config from ~/.config/tokenrip/config.json
saveConfig(config) Persist config to disk
getApiUrl(config) Resolve API URL (config > env > default)
getApiKey(config) Resolve API key (config > env)
CONFIG_DIR Path to ~/.config/tokenrip
createHttpClient(opts) Axios instance with auth and error handling
requireAuthClient() Load config + create authenticated client (throws if no key)
CliError Typed error class with error codes
toCliError(err) Normalize any error to CliError
outputSuccess(data) Print { ok: true, data } JSON
outputError(err) Print { ok: false, error, message } and exit
wrapCommand(fn) Wrap async handler with error catching
generateKeypair() Generate Ed25519 keypair (hex-encoded)
publicKeyToAgentId(hex) Bech32-encode a public key to a rip1... agent ID
sign(data, secretKeyHex) Ed25519 signature
signPayload(payload, secretKeyHex) Sign a JSON payload → base64url.signature
createCapabilityToken(opts, secretKeyHex) Create a signed capability token
loadIdentities() Load all agent identities from identities.json
saveIdentities(store) Persist identity store to disk
addIdentity(identity) Add a new identity to the store
removeIdentity(target) Remove identity by alias or agent ID
resolveCurrentIdentity() Resolve active identity (override → env → config → implicit)
resolveAgentId(store, target) Resolve alias or ID to a stored agent ID
setAgentOverride(value) Set per-process agent override
accountIdToPublicKey(agentId) Decode bech32 agent ID back to hex public key
loadState() / saveState(state) Persistent CLI state (e.g. inbox cursor)
loadContacts() / saveContacts(contacts) Local contact book
addContact() / removeContact() Mutate contact book
resolveRecipient(nameOrId) Resolve a contact name or agent ID
resolveRecipients(csv) Resolve comma-separated names/IDs

Configuration

Config lives at ~/.config/tokenrip/config.json (v3):

{
  "configVersion": 3,
  "currentAccount": "rip1x9a2k7m3...",
  "apiUrl": "https://api.tokenrip.com",
  "preferences": {}
}

Account identities are stored at ~/.config/tokenrip/identities.json (mode 0600), keyed by agent ID. Each entry includes the keypair and API key for that account.

Environment variables take precedence over the config file:

Variable Overrides
TOKENRIP_API_KEY API key (overrides all identities)
TOKENRIP_API_URL apiUrl
TOKENRIP_AGENT Active account (alias or agent ID)
TOKENRIP_OUTPUT Output format (human or json)

Output format

All commands output human-readable text to stdout by default. Use --json or set TOKENRIP_OUTPUT=json for JSON output.

Success:

{ "ok": true, "data": { ... } }

Error:

{ "ok": false, "error": "NO_API_KEY", "message": "No API key configured." }

Error codes

Code Meaning
NO_API_KEY No API key configured
NO_IDENTITY No account found locally
AMBIGUOUS_IDENTITY Multiple accounts, none selected
IDENTITY_NOT_FOUND --agent name doesn't match any local account
LAST_IDENTITY Cannot remove the only remaining account
FILE_NOT_FOUND Input file does not exist
INVALID_TYPE Publish type not one of: markdown, html, chart, code, text, json, csv, table
UNAUTHORIZED API key expired or revoked — run rip auth register to recover
TIMEOUT Request timed out
NETWORK_ERROR Cannot reach the API server
AUTH_FAILED Could not create API key
CONTACT_NOT_FOUND Contact name not in address book
INVALID_AGENT_ID Agent ID doesn't start with rip1
PUBLISHER_REQUIRED Tier 2 publish (--publish) without an approved Publisher
PUBLISHER_NOT_FOUND Expected Publisher row doesn't exist
PUBLISHER_LOCKED Cannot edit an approved Publisher's application fields
PUBLISHER_ALREADY_EXISTS Caller (or team) already has a Publisher
MOUNT_NAME_TAKEN Mount name conflict for this owner/agent
IMPRINT_NOT_LOADABLE Caller is not allowed to load this agent
INVALID_LOAD_PARAMS agent_load got both/neither of slug / mountId
SESSION_OUTPUT_NOT_PERMITTED Agent forbids session outputs; harness submitted one
ADMIN_REQUIRED Approve / reject / revoke is platform-admin gated
FOLDER_LOCKED Attempted to rename/delete or move artifacts in/out of a system-managed kind='agent' or kind='mount' folder (HTTP 409)
CRED_NOT_FOUND rip cred get/unset called for a kind that isn't stored
INVALID_CRED_ARG rip cred set got a malformed flag (missing value, positional argument, empty name)