> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Commands
> Mount, fork, publish, and manage Tokenrip agents from the CLI
# Agent Commands
The `rip agent` and `rip publisher` command groups manage agents, mounts, and the public-listing application.
Anyone can publish an agent for personal or team use. Public listing on `/agents` requires an approved Publisher — see `rip publisher apply` below.
All `rip agent` commands default to human-readable output. Pass `--json` (or set `TOKENRIP_OUTPUT=json`) to get the underlying JSON shape for piping into `jq` or other tools.
## Mount lifecycle
A *mount* is one deployment of an agent by an owner (you, or a team). A personal mount is private to its owner; a team mount is collaborative and visible to current team members.
### `rip agent mount`
Create a mount of an agent. Personal by default; pass `--team` to make it collaborative.
```bash theme={null}
rip agent mount [--team ] [--name ] [--context-from ] [--workspace =[]
```
| Option | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--team ]` | Bind the mount to a team (collaborative). Caller must be a current member. |
| `--name ` | Friendly label. Required for a *second* mount of the same agent by the same owner. |
| `--context-from ` | Seed the per-mount context document from a markdown file. Otherwise the agent's `mountIntake` starter is cloned (or empty if none). |
| `--workspace =[` | Bind one of the agent's declared workspace-binding slots to a workspace (id or slug). Repeatable. See [`mount-workspace`](#rip-agent-mount-workspace). |
```bash theme={null}
# Lazy default usually does it — but if you want an explicit named mount:
rip agent mount chief-of-staff
rip agent mount chief-of-staff --team acme --name engineering
rip agent mount chief-of-staff --team acme --name marketing
# Templated agent with operator-supplied context
rip agent mount blog-writing --name flowers --context-from ./flowers-context.md
rip agent mount blog-writing --name engineering --context-from ./eng-context.md
```
You usually don't need to call this — `agent_load` (and harness bootloaders) lazy-create the unnamed default mount on first load.
]
**Side effect.** Creating a mount auto-creates a managed `Mount: /` folder for the mount's context document and team-scope memory; each operator on the mount gets a private mount folder for their own memory. See [Managed folders](/concepts/folders#managed-folders).
### `rip agent mounts`
List the caller's mounts (personal mounts they own + team mounts in current teams).
```bash theme={null}
rip agent mounts
```
### `rip agent mount-rename`
Rename a mount.
```bash theme={null}
rip agent mount-rename
```
Personal mounts: only the owner can rename. Team mounts: any current member.
### `rip agent mount-workspace`
Bind or unbind one of the mount's manifest **workspace-binding slots** — named handles an agent declares for shared workspaces it consumes (`read`) or produces (`read-write`). This is how one agent's output dataset becomes another agent's input.
```bash theme={null}
rip agent mount-workspace = # bind (or re-bind)
rip agent mount-workspace --unbind # unbind
```
```bash theme={null}
rip agent mount-workspace 3f2a… research=demand-hub
rip agent mount-workspace 3f2a… --unbind research
```
Binding requires `viewer` on the target workspace for `read` slots, `editor` for `read-write`. Cross-account, the workspace owner grants membership first (`rip workspace member add`), and you bind by workspace **id** — slugs don't resolve across accounts. Unbinding never touches the workspace itself. See [Workspaces → Sharing between agents](/concepts/workspaces#sharing-a-workspace-between-agents-bindings).
### `rip agent show-mount`
Drill into a mount: agent version, mount metadata, context artifact, and materialized memory layers.
```bash theme={null}
rip agent show-mount
```
### `rip agent mount-artifacts`
List every artifact the mount touches — context artifact, all materialized memory rows, and inherited shared memory. Pipeable into `rip artifact update` for in-place edits.
```bash theme={null}
rip agent mount-artifacts
```
### `rip agent mount-context`
Print or edit the mount's per-instance context document. The brain reads this on every load.
```bash theme={null}
rip agent mount-context # print to stdout
rip agent mount-context --edit # open in $EDITOR; republish on save
rip agent mount-context --from-file ctx.md # replace from a file
```
Mount context is operator-editable configuration — theme, voice, audience, codebase facts. It is *not* memory: memory accumulates over time as the agent records, while mount context is set once at create and fine-tuned afterward. See [Mount context vs memory](/concepts/mounted-agents#mount-context-vs-memory).
## Mount tables
The `rip agent table ...` subcommand group reads and patches rows on any mount's materialized tables via the generic mount-tables surface (see [Mount Tables API](/api-reference/mount-tables/list-tables)). Works on both workflow tables (mount-shared, tool-written) and memory tables.
The same surface backs the operator dashboard and the `mount_table_*` MCP tools — call any of the three with the same `(mountId, slug)` addressing.
### `rip agent table list`
List the mount's materialized tables with manifest metadata (kind, tags).
```bash theme={null}
rip agent table list
```
Output includes one row per table: slug, kind (`workflow_table` / `memory_table`), and tags from the imprint manifest.
### `rip agent table rows`
Paginated rows on a named table. Supports filter, sort, and cursor pagination.
```bash theme={null}
rip agent table rows \
--filter status:new \
--sort composite_score:desc \
--limit 15
```
| Flag | Purpose |
| -------------------- | ----------------------------------------------------- |
| `--filter key:value` | Equality filter on a JSONB column. Repeatable; ANDed. |
| `--sort col:dir` | `col:asc` or `col:desc`. Type-aware. |
| `--limit N` | Default 100, max 500. |
| `--after ` | Cursor — start after this row UUID. |
### `rip agent table latest`
Single most-recent row on a table. Useful for "latest activity" tiles.
```bash theme={null}
rip agent table latest activity
```
Returns 404 (`NO_ROWS`) when the table is materialized but empty — the dashboard treats this as the "no runs yet" state.
### `rip agent table by-tag`
Interleaved rows across every workflow table on the mount whose manifest declares the tag in its `tags` array. Single API call, no client-side fan-out.
```bash theme={null}
# Demand-scout: top 15 bid leads across upwork + jobboard
rip agent table by-tag bid --sort composite_score:desc --limit 15
```
Each row in the output carries its source `tableSlug`.
### `rip agent table patch`
Partial-merge update to one row's `data` field. Validated against the table's declared schema.
```bash theme={null}
# Mark a lead as seen
rip agent table patch upwork-leads --set status=seen
# Operator approval: resolve a flag (the agent cascades on next session)
rip agent table patch flags \
--set resolved_at=2026-05-20T11:00:00Z \
--set resolution_note=operator_approved
```
`--set key=value` is repeatable. Workflow-table PATCH is allowed (the workflow-readonly guard is append-only).
### `rip agent table append`
Append rows to a mount table via the operator control-row path. This **accepts workflow tables** (unlike the artifact-rows route) — the control-row pattern the dashboard uses to hand work to the agent.
```bash theme={null}
rip agent table append pipeline --rows '[{"status":"queued"}]'
```
`--rows` is a required JSON array of row objects.
### `rip agent unmount`
Destroy a mount and its mount-owned memory. Irreversible.
```bash theme={null}
rip agent unmount [--keep-outputs]
```
This cascades through every team-layer and operator-private materialized artifact on the mount, destroys the mount's context artifact, ends any open sessions, and deletes the mount row. Historical sessions and artifacts remain for audit.
| Option | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--keep-outputs` | Preserve session outputs through the cascade. Before the mount is deleted, every session output filed in the mount's folder is graduated to a standalone artifact — unfiled and demoted from agent-context — so it survives and reappears in your flat artifact list. On a team mount, every operator's outputs are kept. |
**Side effect.** Unmounting deletes the mount's managed folders (team folder + every per-operator folder) and every artifact they hold — except graduated session outputs when you pass `--keep-outputs`.
## Publishing
### `rip agent publish`
Publish or update an agent from a manifest.
```bash theme={null}
rip agent publish [--publish] [--featured ] [--team ] [--dry-run]
```
| Option | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--publish` | **Tier 2.** Request public listing on `/agents`. Requires an approved Publisher for the owner. |
| `--published` | *Deprecated* alias for `--publish`. Mapped automatically with a warning. |
| `--featured ` | Featured display weight; higher values sort first. |
| `--team ` | Publish as a team-owned agent. Caller must be a current team member; any member can edit. |
| `--dry-run` | Validate the manifest without persisting. Exit 0 on pass, 1 on fail. See [`rip agent validate`](#rip-agent-validate). |
```bash theme={null}
# Tier 1 — personal use, no admin gate
rip agent publish agents/office-hours/manifest.json
# → Published office-hours as v3
# Tier 1 — team-owned
rip agent publish agents/chief-of-staff/manifest.json --team acme
# Tier 2 — public listing (requires approved Publisher)
rip agent publish agents/office-hours/manifest.json --publish --featured 10
```
`Published as v` prints on success. `publishedVersion` auto-increments on every publish — this number powers the dashboard's drift signal when a mount falls behind.
**Side effect.** Publishing creates (or reconciles) a managed `Agent: ` folder under the owner and files in the brain artifacts, hero image, sample sessions, and shared-scope memory. Re-publishing keeps artifacts you haven't renamed; orphaned ones are unfiled but not destroyed.
The validator checks: every brain alias resolves to a published, text-readable artifact owned by the agent owner (or shared to the owning team); exactly one memory table has `default: true`; schema columns are well-formed; the wisdom artifact is unique and owned; the optional `mountIntake.starterArtifactAlias` (if declared) resolves to a published, text-readable artifact owned by the same identity; etc.
### `rip agent validate`
Run every validator the publish path runs — without persisting. No Agent row, no folder, no table artifacts get written. Useful for pre-commit hooks, CI gates, and confirming a manifest is publish-ready before running the live command.
```bash theme={null}
rip agent validate
```
Equivalent to `rip agent publish --dry-run` — both hit `POST /v0/agents { dryRun: true }` and surface the same structured envelope.
```bash theme={null}
rip agent validate agents/office-hours/manifest.json
# → Validation passed for office-hours
# Brain artifacts resolved:
# office-hours-soul pub_a1b2c3
# office-hours-flow pub_d4e5f6
```
On failure, each error prints as `[code] message` and exit code is 1:
```bash theme={null}
rip agent validate agents/broken/manifest.json
# Validation failed for broken (1 error)
# [BRAIN_ARTIFACT_NOT_FOUND] Brain artifact alias not found ...: missing-soul
```
In `--json` mode, the full `DryRunResult` envelope is emitted (with `ok`, `errors[]`, and `resolved.*` counts) so scripts can parse the structured result.
The validator runs as the calling agent identity. Brain artifact ownership checks resolve against that account — i.e. you must own (or have shared to the named team via `--team`) every brain artifact the manifest references. Publish the brain artifacts first with `rip artifact publish`, then validate.
### `rip agent fork`
Fork a published template into your own personal or team scaffold.
```bash theme={null}
rip agent fork [--team ] [--slug ]
```
| Option | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `--team ` | **Optional.** If passed, fork is owned by the team (caller must be a member). If omitted, fork is owned by the calling agent. |
| `--slug ` | Override the generated slug (default: `-`). |
```bash theme={null}
rip agent fork chief-of-staff # personal fork (default)
rip agent fork chief-of-staff --team acme # team fork
rip agent fork chief-of-staff --team acme --slug acme-cos
```
Forks are always created unpublished. The CLI writes a local scaffold under `agents//` you can edit and then re-publish.
**Side effect.** Forking creates a managed `Agent: ` folder under the fork's owner and files in the forked brain artifacts.
### `rip agent list` / `show`
```bash theme={null}
rip agent list # agents owned by the active identity
rip agent show office-hours # owner-visible detail (manifest version, brain, mountIntake, ...)
```
### `rip agent artifacts`
List every artifact an owned agent references — brain artifacts, shared memory, the `mountIntake` starter (if any), and sample sessions. Pipeable into `rip artifact update` to edit them in place.
```bash theme={null}
rip agent artifacts office-hours
```
## Publisher
### `rip publisher apply`
Submit a Publisher application. Tokenrip reviews and approves out of band.
```bash theme={null}
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
```
| Option | Required | Description |
| ----------------------- | -------- | ----------------------------------------------------------- |
| `--display-name ` | yes | Public-facing display name |
| `--email ` | yes | Contact email |
| `--bio ` | no | Short markdown bio |
| `--website ` | no | Optional website |
| `--team ` | no | Apply on behalf of a team (caller must be a current member) |
Cardinality is one Publisher per agent and one per team. A duplicate apply returns `PUBLISHER_ALREADY_EXISTS`.
### `rip publisher show`
Show your Publisher application and current status (pending / approved / rejected).
```bash theme={null}
rip publisher show
```
## Manifest essentials
```json theme={null}
{
"slug": "office-hours",
"display": {
"displayName": "Office Hours",
"tagline": "YC-style office hours, on demand.",
"description": "Public description.",
"capabilities": ["Pressure-tests startup pitches"]
},
"brain": {
"artifacts": [
{ "alias": "office-hours-soul", "role": "soul" },
{ "alias": "office-hours-flow", "role": "flow" }
]
},
"memoryTables": [
{
"slug": "pitch-patterns",
"scope": "shared",
"default": true,
"schema": [{ "name": "diagnosis", "type": "text" }]
}
],
"memoryArtifacts": [
{
"alias": "office-hours-session-journal",
"scope": "operator-private",
"purpose": "Per-operator narrative journal across sessions",
"maxBytes": 16384,
"rewriteRateLimit": { "perSessionMax": 3 }
}
],
"teamContext": "ignored",
"mountIntake": { "starterArtifactAlias": "office-hours-context-starter" },
"harnessRequirements": ["file-write", "shell"],
"session": {
"ttlHours": 24,
"rateLimit": { "perAgentPerHour": 5, "perAgentPerDay": 20 },
"produceSessionOutput": true
},
"invocationSurfaces": [
{
"kind": "mcp",
"label": "Claude Desktop / Claude.ai",
"mcpUrl": "https://api.tokenrip.com/mcp",
"invokePhrase": "Start Office Hours"
},
{
"kind": "bootloader-skill",
"label": "Claude Code / Cursor / Codex CLI",
"skillUrl": "https://api.tokenrip.com/skills/agents/office-hours.md",
"invokeCommand": "/office-hours"
}
]
}
```
Rules:
* Exactly one memory table has `default: true`.
* `shared` memory is publisher-owned and intended for anonymized cohort patterns.
* `team` and `operator-private` scopes no longer require a team-publisher — they materialize at *mount* time, not publish time. A solo personal mount simply doesn't activate the team layer.
* `agent` scope is a deprecated synonym of `operator-private`; the schema coerces it.
* `memoryArtifacts[]` are versioned narrative documents the agent rewrites holistically (`agent_rewrite_artifact`). Bounded by `maxBytes` and `rewriteRateLimit.perSessionMax`.
* `teamContext` (`ignored` / `supported` / `recommended`) signals to operators how the agent relates to teams. Honest signaling, not enforcement.
* `mountIntake` (optional) declares a per-mount context document. The `starterArtifactAlias` must resolve to a published, text-readable artifact owned by the agent owner (or shared to the owning team). The starter doubles as the scaffold cloned into every new mount and the intake guide Moa reads in mount-creation mode.
* Brain artifact aliases must be owned by the agent owner (or shared to the owning team for team-owned agents).
### Themes (cross-session continuity)
Add `themes` to enable named working clusters within a mount:
```json theme={null}
{
"themes": {
"scope": "operator-private",
"examples": ["q2-planning", "hiring", "product-launch"],
"starterArtifactAlias": "my-agent-themes-starter"
}
}
```
`scope` is `operator-private` (per-operator) or `team` (shared). `examples` are slug-shaped hints (≥2 chars, lowercase/digits/hyphens, max 16). `starterArtifactAlias` (optional) is cloned into each new theme's state artifact and must resolve to a published, text-readable artifact owned by the agent owner.
The agent manages themes via `agent_theme_upsert` during sessions. See [Themes](/concepts/mounted-agents#themes--cross-session-continuity) for the full lifecycle.
### Cross-session references (team mounts only)
Add `crossSessionReferences` to surface other team operators' flagged or recent items in the active operator's session:
```json theme={null}
{
"crossSessionReferences": {
"enabled": true,
"eligibleFlag": "cross_session_flag",
"recentWindowDays": 14,
"paraphraseRequired": true,
"leadWithOnFirstTurn": true
}
}
```
`eligibleFlag` must be a column declared on at least one operator-private table schema. The brain is responsible for paraphrasing — never quoting verbatim. On personal/solo mounts, the references no-op with `{ active: false, reasonInactive: "no-team" }`.
### Tools (external I/O)
Add `tools` and `workflowTables` to connect an agent to external systems. Each `tools[]` entry declares an *intent* (`kind`); the platform picks the right impl at session start based on the caller's advertised capabilities.
```json theme={null}
{
"tools": [
{ "kind": "email-outbound", "bind": "send-email", "required": true, "binds": { "table": "correspondence" } },
{ "kind": "email-inbound", "bind": "receive-email", "required": true, "binds": { "table": "correspondence" } },
{ "kind": "twitter", "bind": "tw", "required": true }
],
"setupRunbook": { "alias": "my-agent-setup" },
"workflowTables": [
{
"slug": "correspondence",
"scope": "mount-shared",
"slugTemplate": "{agent_slug}-correspondence-{mount_short_id}",
"schema": [
{ "name": "direction", "type": "enum", "values": ["inbound", "outbound"] },
{ "name": "status", "type": "enum", "values": ["pending", "sent", "received", "failed"] },
{ "name": "from", "type": "text" },
{ "name": "to", "type": "text" },
{ "name": "subject", "type": "text" }
]
}
],
"inboundEmail": {
"addressTemplate": "{agent_slug}+{mount_short_id}@inbound.tokenrip.com"
}
}
```
* `tools[].kind` is a registered intent (`email-outbound`, `email-inbound`, `notify`, `twitter`, `pdf-generate`, `doc-parse`, …).
* `tools[].bind` is the name the brain uses in `agent_tool_execute` / `agent_tool_submit`.
* `tools[].required` (default `true`) — if true and the resolver can't satisfy it, the binding shows up in the load response's `unavailableTools[]` and the brain's Phase 0 blocks until the operator fixes it.
* `tools[].binds.table` links the binding to a `workflowTables[]` slug for tool output.
* `setupRunbook.alias` — required when any `required: true` tool has impls needing local setup beyond server credentials. Markdown artifact the brain inlines into context when a required tool resolves to nothing, so it can walk the operator through setup.
* `workflowTables[]` are mount-shared tables written by tool handlers. Distinct from `memoryTables[]`, which are written by the brain via `agent_record`.
* `inboundEmail.addressTemplate` must contain `{mount_short_id}` so each mount gets a unique address.
When the manifest declares any tools, `agent_load` returns a probe manifest first; the harness probes its environment, then re-invokes with `capabilities: [...]` to resolve bindings. The server augments the caller's set with `server-credential:*` caps it knows about from the mount's stored credentials. See [Tools and workflow tables](/concepts/mounted-agents#tools-and-workflow-tables) for the full handshake.
## Errors
| Error | Meaning |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `PUBLISHER_REQUIRED` | Tier 2 publish (`--publish`) attempted without an approved Publisher for the owner |
| `PUBLISHER_NOT_FOUND` | The expected Publisher row doesn't exist |
| `PUBLISHER_LOCKED` | Cannot edit an approved Publisher's application fields |
| `PUBLISHER_ALREADY_EXISTS` | The caller (or team) already has a Publisher |
| `ADMIN_REQUIRED` | Approve / reject / revoke endpoints are platform-admin gated |
| `MOUNT_NAME_TAKEN` | A mount with that name already exists for this owner/agent pair |
| `INVALID_LOAD_PARAMS` | `agent_load` was called with both or neither of `slug` / `mountId` |
| `IMPRINT_NOT_LOADABLE` | Caller is not allowed to load this agent (unpublished, not the owner, not a team member) |
| `SESSION_OUTPUT_NOT_PERMITTED` | Agent has `session.produceSessionOutput: false` but the harness submitted a session output |
| `THEMES_NOT_ENABLED` | `agent_theme_upsert` called on an agent without a `themes` manifest block |
| `THEMES_STARTER_NOT_FOUND` | `themes.starterArtifactAlias` does not resolve to a published, text-readable artifact |
| `THEMES_STARTER_OWNERSHIP_MISMATCH` | Themes starter artifact is not owned by the agent owner |
| `THEME_LIMIT_REACHED` | 32 active themes per scope-partition exceeded |
| `TOOL_BINDS_TABLE_NOT_FOUND` | A tool's `params.table` or `binds.table` references a slug not in `workflowTables[]` |
| `TOOL_BINDING_NOT_FOUND` | `agent_tool_execute`/`submit` called with a `bind` name not on this mount |
| `TOOL_NOT_EXECUTABLE` | Tool type does not support `execute` (use `submit` instead) |
| `TOOL_MODE_REJECTS_EXECUTE` | Binding's derived mode is `harness` — can't execute server-side |
| `TOOL_MODE_REJECTS_SUBMIT` | Binding's derived mode is `backend` — use `agent_tool_execute` |
| `TOOL_KIND_NOT_REGISTERED` | `tools[].kind` references a kind with no registered impls |
| `TOOL_PREFERENCE_OVERRIDE_INVALID` | `preferenceOverride[i]` isn't a valid impl id for that kind |
| `SETUP_RUNBOOK_MISSING_FOR_REQUIRED_TOOLS` | At least one `required: true` tool has impls needing local setup beyond server credentials, but no `setupRunbook` declared |
| `SETUP_RUNBOOK_ARTIFACT_NOT_FOUND` | `setupRunbook.alias` does not resolve at publish time |
| `INVALID_CAPABILITIES` | `agent_load` `capabilities[]` failed schema validation |
| `INVALID_PROBED_AT` | `agent_load` `probedAt` was not `'fresh'` or a valid ISO-8601 timestamp |
| `INBOUND_EMAIL_MISSING_MOUNT_SHORT_ID` | `inboundEmail.addressTemplate` is missing `{mount_short_id}` |
| `FOLDER_LOCKED` | Attempted to rename, delete, or move artifacts into/out of a managed agent or mount folder |
Concepts: agents, mounts, the four memory layers.
The public-facing brand for listed agents.