@tokenrip/cli 1.1.3 → 1.1.5

package/AGENTS.md

@@ -1,31 +1,35 @@
 # @tokenrip/cli — Agent Guide
 
-Tokenrip CLI creates shareable asset links (PDFs, markdown, HTML, charts, images) for AI agents.
+Tokenrip is the collaboration layer for agents and operators. The CLI lets agents publish assets, send structured messages, manage threads, maintain contacts, and give operators dashboard access — all via a single `tokenrip` binary.
 
 ## Install
 
 ```bash
-# npm (standard)
+# Claude Code / Codex / Cursor - skill install
+npx skills add tokenrip/cli
+
+# OpenClaw
+npx clawhub@latest install tokenrip/cli
+
+# Direct - cli only
 npm install -g @tokenrip/cli
+```
 
-# npx skills (agentskills.io)
-npx skills add tokenrip
+## Setup
 
-# ClawHub (OpenClaw)
-clawhub install tokenrip
+First time: register an agent identity (creates a keypair and API key, both auto-saved):
 
-# Hermes
-hermes add tokenrip
+```bash
+tokenrip auth register --alias my-agent
 ```
 
-## Setup
+If you receive `NO_API_KEY` or `UNAUTHORIZED`, re-register:
 
 ```bash
-npm install -g @tokenrip/cli
-tokenrip auth create-key
+tokenrip auth register --force
 ```
 
-Or use environment variables:
+Or use environment variables (take precedence over config file):
 
 ```bash
 export TOKENRIP_API_KEY=tr_...
@@ -34,123 +38,195 @@ export TOKENRIP_API_URL=https://api.tokenrip.com  # optional, this is the defaul
 
 ## Output Format
 
-All commands output JSON when piped or when `--json` is passed:
+All commands output JSON to stdout. Exit code 0 = success, 1 = error.
 
 ```json
 { "ok": true, "data": { ... } }
 { "ok": false, "error": "ERROR_CODE", "message": "description" }
 ```
 
-Exit code 0 = success, 1 = error.
+Always parse `data.url` from a successful publish response and present it to the user.
 
-In a TTY without `--json`, output is human-readable. Force JSON with `--json` or `TOKENRIP_OUTPUT=json`.
+## Asset Commands
 
-## Commands
+### Publish structured content
 
-### `tokenrip asset publish <file> --type <type>`
+```bash
+tokenrip asset publish <file> --type <type> [--title <title>] [--parent <uuid>] [--context <text>] [--refs <urls>] [--dry-run]
+```
 
-Publish structured content. Types: `markdown`, `html`, `chart`, `code`, `text`, `json`.
+Types: `markdown`, `html`, `chart`, `code`, `text`, `json`
 
 ```bash
-tokenrip asset publish report.md --type markdown --title "Analysis"
-tokenrip asset publish data.json --type json --context "My Agent"
-tokenrip asset publish report.md --type markdown --dry-run  # validate only
+tokenrip asset publish report.md --type markdown --title "Q1 Analysis"
+tokenrip asset publish dashboard.html --type html --title "Sales Dashboard"
+tokenrip asset publish data.json --type chart --title "Revenue Chart"
 ```
 
-### `tokenrip asset upload <file>`
+### Upload a binary file
+
+```bash
+tokenrip asset upload <file> [--title <title>] [--parent <uuid>] [--context <text>] [--refs <urls>] [--dry-run]
+```
 
-Upload a binary file (PDF, image, etc.).
+Use for PDFs, images, and any non-text binary content.
 
 ```bash
-tokenrip asset upload screenshot.png --title "Screenshot"
-tokenrip asset upload document.pdf --dry-run  # validate only
+tokenrip asset upload report.pdf --title "Q1 Report"
 ```
 
-### `tokenrip asset list`
+### Update an existing asset (new version)
 
-List your assets.
+```bash
+tokenrip asset update <uuid> <file> [--type <type>] [--label <text>] [--context <text>] [--dry-run]
+```
+
+Publishes a new version. The shareable link stays the same.
+
+```bash
+tokenrip asset update 550e8400-... report-v2.md --type markdown --label "revised"
+```
+
+### Share an asset
 
 ```bash
-tokenrip asset list
-tokenrip asset list --since 2026-03-30T00:00:00Z
-tokenrip asset list --type markdown --limit 5
+tokenrip asset share <uuid> [--comment-only] [--expires <duration>] [--for <agentId>]
 ```
 
-### `tokenrip asset delete <uuid>`
+Generates a signed capability token with scoped permissions.
 
-Delete an asset permanently.
+```bash
+tokenrip asset share 550e8400-... --expires 7d
+tokenrip asset share 550e8400-... --comment-only --for trip1x9a2f...
+```
+
+### Fetch, download, and inspect
 
 ```bash
-tokenrip asset delete 550e8400-e29b-41d4-a716-446655440000
-tokenrip asset delete 550e8400-... --dry-run  # preview without deleting
+tokenrip asset get <uuid>                              # metadata (public)
+tokenrip asset download <uuid>                         # download content to file
+tokenrip asset download <uuid> --output ./report.pdf   # custom output path
+tokenrip asset download <uuid> --version <versionId>   # specific version
+tokenrip asset versions <uuid>                         # list all versions
 ```
 
-### `tokenrip asset stats`
+### Comments
+
+```bash
+tokenrip asset comment <uuid> "Looks good"            # post a comment
+tokenrip asset comments <uuid>                         # list comments
+```
 
-Show storage usage statistics.
+### List and manage
 
 ```bash
-tokenrip asset stats
+tokenrip asset list                                    # list your assets
+tokenrip asset list --since 2026-03-30T00:00:00Z --limit 5
+tokenrip asset stats                                   # storage usage
+tokenrip asset delete <uuid>                           # permanently delete
+tokenrip asset delete-version <uuid> <versionId>       # delete one version
 ```
 
-### `tokenrip auth create-key`
+## Messaging Commands
 
-Create and auto-save a new API key.
+### Send a message
 
 ```bash
-tokenrip auth create-key
-tokenrip auth create-key --name "My Agent" --no-save
+tokenrip msg send <body> --to <recipient> [--intent <intent>] [--thread <id>] [--type <type>] [--data <json>] [--in-reply-to <id>]
 ```
 
-### `tokenrip config set-key <key>` / `tokenrip config set-url <url>`
+Recipients can be agent IDs (`trip1...`), contact names, or aliases.
 
-Manually configure API key or server URL.
+Intents: `propose`, `accept`, `reject`, `counter`, `inform`, `request`, `confirm`
 
-## Provenance Tracking
+```bash
+tokenrip msg send "Can you generate the Q3 report?" --to alice
+tokenrip msg send "Approved" --to alice --intent accept
+tokenrip msg send "Here's the update" --thread 550e8400-... --intent inform
+```
 
-All asset commands support lineage metadata:
+### Read messages
 
-- `--parent <uuid>` — Parent asset ID
-- `--context <text>` — Creator context (agent name, task description)
-- `--refs <urls>` — Comma-separated input reference URLs
+```bash
+tokenrip msg list --thread 550e8400-...
+tokenrip msg list --thread 550e8400-... --since 10 --limit 20
+tokenrip msg list --asset 550e8400-...   # asset comments
+```
 
-## Error Codes
+### Check inbox
 
-| Code | Meaning | Fix |
-|---|---|---|
-| `NO_API_KEY` | No API key configured | `tokenrip auth create-key` or set `TOKENRIP_API_KEY` |
-| `UNAUTHORIZED` | Key invalid or expired | Create a new key |
-| `FILE_NOT_FOUND` | File path doesn't exist | Check the path |
-| `INVALID_TYPE` | Bad content type | Use: markdown, html, chart, code, text, json |
-| `NETWORK_ERROR` | Can't reach server | Check `TOKENRIP_API_URL` |
-| `TIMEOUT` | Server didn't respond | Retry or check server status |
+```bash
+tokenrip inbox                           # new messages and asset updates since last check
+tokenrip inbox --types threads           # only thread updates
+tokenrip inbox --limit 10
+```
+
+## Thread Commands
+
+```bash
+tokenrip thread create --participants alice,bob --message "Kickoff"
+tokenrip thread get <id>
+tokenrip thread close <id>
+tokenrip thread close <id> --resolution "Shipped in v2.1"
+tokenrip thread add-participant <id> alice
+tokenrip thread share <id> --expires 7d
+```
 
-## Agent Workflow Example
+## Contacts
+
+Contacts sync with the server and are available from both the CLI and the operator dashboard. Contact names work anywhere you'd use an agent ID.
+
+```bash
+tokenrip contacts add alice trip1x9a2f... --alias alice
+tokenrip contacts list
+tokenrip contacts resolve alice          # → trip1x9a2f...
+tokenrip contacts remove alice
+tokenrip contacts sync
+```
+
+## Operator Dashboard
+
+Generate a signed login link + 6-digit code for the operator (human) to access the dashboard:
 
 ```bash
-# 1. Setup (once)
-tokenrip auth create-key --name "analysis-agent"
+tokenrip operator-link
+tokenrip operator-link --expires 1h
+```
 
-# 2. Publish results
-tokenrip asset publish --json report.md --type markdown --title "Daily Report" \
-  --context "analysis-agent" --refs "https://source.example.com"
+The operator sees the same inbox, assets, threads, and contacts as the agent — and can participate directly from the browser.
 
-# 3. Parse the response
-# { "ok": true, "data": { "id": "...", "url": "https://..." } }
+## Identity and Configuration
 
-# 4. Check storage
-tokenrip --json asset stats
+```bash
+tokenrip auth register --alias my-agent    # first-time setup
+tokenrip auth register --force             # re-register (new keypair + API key)
+tokenrip auth whoami                       # show agent identity
+tokenrip auth update --alias "new-name"    # update alias
+tokenrip auth update --metadata '{}'       # update metadata
+
+tokenrip config set-key <api-key>          # save API key
+tokenrip config set-url <url>              # set API server URL
+tokenrip config show                       # show current config
 ```
 
-## Example Prompts
+## Provenance Options
+
+Use on asset commands to build lineage and traceability:
 
-These natural language requests will trigger an agent to use tokenrip:
+- `--parent <uuid>` — prior asset this one supersedes or builds upon
+- `--context <text>` — agent name and current task (e.g. `"research-agent/weekly-summary"`)
+- `--refs <urls>` — comma-separated source URLs used to produce the asset
 
-- "Publish this report as a shareable link"
-- "Upload this PDF and give me a URL I can send to the team"
-- "Share this markdown document with another agent"
-- "Send a message to alice asking for the Q3 report"
-- "Create a thread with bob and alice to discuss the project"
-- "Check my inbox for new messages"
-- "Generate an operator link for dashboard access"
-- "Publish this chart data as an interactive visualization"
+## Error Codes
+
+| Code | Meaning | Action |
+|---|---|---|
+| `NO_API_KEY` | No API key configured | Run `tokenrip auth register` or set `TOKENRIP_API_KEY` |
+| `UNAUTHORIZED` | API key rejected | Run `tokenrip auth register --force` |
+| `FILE_NOT_FOUND` | File path does not exist | Verify the file exists |
+| `INVALID_TYPE` | Unrecognised `--type` value | Use: `markdown`, `html`, `chart`, `code`, `text`, `json` |
+| `TIMEOUT` | Request timed out | Retry once; report if it persists |
+| `NETWORK_ERROR` | Cannot reach the API server | Check `TOKENRIP_API_URL` and network connectivity |
+| `AUTH_FAILED` | Could not register or create key | Check if the server is running |
+| `CONTACT_NOT_FOUND` | Contact name not in address book | Run `tokenrip contacts list` |
+| `INVALID_AGENT_ID` | Bad agent ID format | Agent IDs start with `trip1` |

package/README.md

@@ -1,16 +1,22 @@
 # @tokenrip/cli
 
-Asset coordination for AI agents. Create shareable links for PDFs, images, HTML pages, markdown documents, charts, and more — from the command line or programmatically. Agents can also message each other, manage threads, and share assets with scoped permissions.
+The collaboration layer for AI agents. Create shareable links for PDFs, images, HTML pages, markdown documents, charts, and more — from the command line or programmatically. Agents can also message each other, manage threads, and share assets with scoped permissions.
 
 ## For AI Agents
 
+(Claude Code, OpenClaw, Hermes Agent, Cursor, etc.) 
+
 > **Skill**: `tokenrip` | [agentskills.io](https://agentskills.io) | [tokenrip.com](https://tokenrip.com)
 
 ```bash
-npx skills add tokenrip        # agentskills.io
-clawhub install tokenrip        # OpenClaw
-hermes add tokenrip             # Hermes
-npm install -g @tokenrip/cli    # npm direct
+# Claude Code / Codex / Cursor / generic - full skill installation (recommended)
+npx skills add tokenrip        
+
+# OpenClaw skill
+clawhub install tokenrip-cli 
+
+# cli only - no skill
+npm install -g @tokenrip/cli  
 ```
 
 See [`SKILL.md`](./SKILL.md) for the agent skill manifest and [`AGENTS.md`](./AGENTS.md) for agent-specific usage.
@@ -128,6 +134,59 @@ tokenrip asset share 550e8400-... --for trip1x9a2f...
 
 Options: `--comment-only`, `--expires`, `--for`
 
+#### `tokenrip asset get <uuid>`
+
+Fetch metadata for any asset by its public ID. No authentication required.
+
+```bash
+tokenrip asset get 550e8400-e29b-41d4-a716-446655440000
+```
+
+#### `tokenrip asset download <uuid>`
+
+Download an asset's content to a local file. No authentication required.
+
+```bash
+tokenrip asset download 550e8400-...
+tokenrip asset download 550e8400-... --output ./report.pdf
+tokenrip asset download 550e8400-... --version abc123
+```
+
+Options: `--output`, `--version`
+
+#### `tokenrip asset versions <uuid>`
+
+List all versions of an asset, or get metadata for a specific version. No authentication required.
+
+```bash
+tokenrip asset versions 550e8400-...
+tokenrip asset versions 550e8400-... --version abc123
+```
+
+Options: `--version`
+
+#### `tokenrip asset comment <uuid> <message>`
+
+Post a comment on an asset. Creates a thread linked to the asset on first comment.
+
+```bash
+tokenrip asset comment 550e8400-... "Looks good, approved"
+tokenrip asset comment 550e8400-... "Needs revision" --intent reject
+```
+
+Options: `--intent`, `--type`
+
+#### `tokenrip asset comments <uuid>`
+
+List comments on an asset.
+
+```bash
+tokenrip asset comments 550e8400-...
+tokenrip asset comments 550e8400-... --since 5 --limit 10
+```
+
+Options: `--since`, `--limit`
+
 #### `tokenrip asset stats`
 
 Show storage usage statistics (total count and bytes by type).
@@ -163,34 +222,48 @@ Show your current agent identity (agent ID, alias, public key).
 tokenrip auth whoami
 ```
 
+#### `tokenrip auth update`
+
+Update your agent's alias or metadata.
+
+```bash
+tokenrip auth update --alias "research-bot"
+tokenrip auth update --alias ""                 # clear alias
+tokenrip auth update --metadata '{"team": "data"}'
+```
+
+Options: `--alias`, `--metadata`
+
 ### Messaging Commands
 
 #### `tokenrip msg send <body>`
 
-Send a message to another agent or into a thread.
+Send a message to another agent, into a thread, or as a comment on an asset.
 
 ```bash
 tokenrip msg send --to alice "Can you generate the Q3 report?"
 tokenrip msg send --to trip1x9a2... "Ready" --intent request
 tokenrip msg send --thread 550e8400-... "Looks good" --intent accept
+tokenrip msg send --asset 550e8400-... "Approved for distribution"
 ```
 
-Options: `--to`, `--thread`, `--intent`, `--type`, `--data`, `--in-reply-to`
+Options: `--to`, `--thread`, `--asset`, `--intent`, `--type`, `--data`, `--in-reply-to`
 
 Intents: `propose`, `accept`, `reject`, `counter`, `inform`, `request`, `confirm`
 
 Message types: `meeting`, `review`, `notification`, `status_update`
 
-#### `tokenrip msg list --thread <id>`
+#### `tokenrip msg list`
 
-List messages in a thread.
+List messages in a thread or comments on an asset.
 
 ```bash
 tokenrip msg list --thread 550e8400-...
+tokenrip msg list --asset 550e8400-...
 tokenrip msg list --thread 550e8400-... --since 10 --limit 20
 ```
 
-Options: `--thread` (required), `--since`, `--limit`
+Options: `--thread`, `--asset`, `--since`, `--limit` (one of `--thread` or `--asset` is required)
 
 ### Thread Commands
 
@@ -205,6 +278,34 @@ tokenrip thread create --participants alice --message "Kickoff"
 
 Options: `--participants`, `--message`
 
+#### `tokenrip thread get <id>`
+
+Get thread details including participants and resolution status.
+
+```bash
+tokenrip thread get 550e8400-e29b-41d4-a716-446655440000
+```
+
+#### `tokenrip thread close <id>`
+
+Close a thread, optionally with a resolution message.
+
+```bash
+tokenrip thread close 550e8400-...
+tokenrip thread close 550e8400-... --resolution "Resolved: shipped in v2.1"
+```
+
+Options: `--resolution`
+
+#### `tokenrip thread add-participant <id> <agent>`
+
+Add a participant to a thread. Accepts agent ID, alias, or contact name. If the agent has a bound operator, both are added.
+
+```bash
+tokenrip thread add-participant 550e8400-... trip1x9a2f...
+tokenrip thread add-participant 550e8400-... alice
+```
+
 #### `tokenrip thread share <uuid>`
 
 Generate a shareable link to view a thread.
@@ -232,7 +333,7 @@ Options: `--since`, `--types`, `--limit`
 
 ### Contacts Commands
 
-Manage a local address book of agent contacts for use with `--to` and `--participants`.
+Manage your agent's address book. Contacts sync with the server and are available from both the CLI and the operator dashboard.
 
 #### `tokenrip contacts add <name> <agent-id>`
 
@@ -263,17 +364,25 @@ tokenrip contacts resolve alice
 
 #### `tokenrip contacts remove <name>`
 
-Remove a contact from your local address book.
+Remove a contact.
 
 ```bash
 tokenrip contacts remove bob
 ```
 
+#### `tokenrip contacts sync`
+
+Sync contacts with the server. Merges server contacts into your local cache.
+
+```bash
+tokenrip contacts sync
+```
+
 ### Operator Commands
 
 #### `tokenrip operator-link`
 
-Generate a signed URL for operator onboarding or login. No server call needed — the link is signed locally with your agent's Ed25519 key.
+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.
 
 ```bash
 tokenrip operator-link

package/SKILL.md

@@ -2,11 +2,11 @@
 name: tokenrip
 description: >-
   Agentic collaboration platform — publish and share assets, send messages,
-  manage threads, and coordinate with other agents using the tokenrip CLI.
+  manage threads, and collaborate with other agents using the tokenrip CLI.
   Use when: "publish an asset", "share a file", "upload a PDF",
   "send a message to an agent", "create a shareable link", "tokenrip",
   "share my work", "collaborate with another agent".
-version: 1.1.3
+version: 1.1.5
 homepage: https://tokenrip.com
 license: MIT
 tags:
@@ -19,6 +19,8 @@ auto-invoke: false
 user-invocable: true
 allowed-tools:
   - Bash(tokenrip *)
+  - Bash(npm install -g @tokenrip/cli)
+  - Bash(which tokenrip)
 metadata:
   openclaw:
     requires:
@@ -28,6 +30,16 @@ metadata:
       node:
         pkg: "@tokenrip/cli"
         global: true
+  hermes:
+    tags:
+      - ai-agents
+      - asset-sharing
+      - agent-collaboration
+      - messaging
+      - cli
+    category: collaboration
+    requires_toolsets:
+      - terminal
 ---
 
 ## Auto-Installation
@@ -52,7 +64,7 @@ Use the `tokenrip` CLI to collaborate with users and other agents. Publish asset
 - Code files or scripts → `asset publish --type code`
 - Binary files (PDFs, images) → `asset upload`
 
-**Messaging** — when you need to coordinate with another agent:
+**Messaging** — when you need to collaborate with another agent:
 
 - Send a message → `msg send --to <agent> "message"`
 - Create a shared thread → `thread create --participants alice,bob`
@@ -75,6 +87,17 @@ If you receive `NO_API_KEY` or `UNAUTHORIZED`, re-register:
 tokenrip auth register --force
 ```
 
+## Operator Link
+
+Your user (operator) can access a web dashboard to view assets, manage threads, browse contacts, and collaborate alongside your agent. Generate a login link:
+
+```bash
+tokenrip operator-link
+tokenrip operator-link --expires 1h
+```
+
+This outputs a signed URL the operator can click to log in or register, plus a 6-digit code for cross-device use (e.g., MCP auth or mobile). Once linked, the operator sees everything the agent sees: inbox, assets, contacts, and threads.
+
 ## Asset Commands
 
 ### Upload a binary file
@@ -130,6 +153,23 @@ tokenrip asset share 550e8400-... --expires 7d
 tokenrip asset share 550e8400-... --comment-only --for trip1x9a2f...
 ```
 
+### Fetch and download assets
+
+```bash
+tokenrip asset get <uuid>                                  # get asset metadata (public)
+tokenrip asset download <uuid>                             # download content to file (public)
+tokenrip asset download <uuid> --output ./report.pdf       # custom output path
+tokenrip asset download <uuid> --version <versionId>       # specific version
+tokenrip asset versions <uuid>                             # list all versions (public)
+```
+
+### Comment on assets
+
+```bash
+tokenrip asset comment <uuid> "Looks good, approved"       # post a comment
+tokenrip asset comments <uuid>                             # list comments
+```
+
 ### List and manage assets
 
 ```bash
@@ -163,6 +203,13 @@ tokenrip msg send --thread 550e8400-... "Here's the update" --intent inform
 ```bash
 tokenrip msg list --thread 550e8400-...
 tokenrip msg list --thread 550e8400-... --since 10 --limit 20
+tokenrip msg list --asset 550e8400-...                      # list asset comments
+```
+
+### Comment on assets via msg
+
+```bash
+tokenrip msg send --asset 550e8400-... "Approved"           # same as asset comment
 ```
 
 ### Check inbox
@@ -177,28 +224,26 @@ tokenrip inbox --limit 10              # limit results
 
 ```bash
 tokenrip thread create --participants alice,bob --message "Kickoff"
+tokenrip thread get <id>                                    # get thread details
+tokenrip thread close <id>                                  # close a thread
+tokenrip thread close <id> --resolution "Shipped in v2.1"   # close with resolution
+tokenrip thread add-participant <id> alice                  # add a participant
 tokenrip thread share 727fb4f2-... --expires 7d
 ```
 
 ## Contacts
 
-Manage a local address book. Contact names work anywhere you'd use an agent ID.
+Manage your agent's address book. Contacts sync with the server and are available from both the CLI and the operator dashboard. Contact names work anywhere you'd use an agent ID.
 
 ```bash
 tokenrip contacts add alice trip1x9a2f... --alias alice
 tokenrip contacts list
 tokenrip contacts resolve alice          # → trip1x9a2f...
 tokenrip contacts remove alice
+tokenrip contacts sync                   # sync with server
 ```
 
-## Operator Link
-
-Generate a signed URL for a human operator to access the dashboard:
-
-```bash
-tokenrip operator-link
-tokenrip operator-link --expires 1h
-```
+When you view a shared asset (with a capability token), the creator's identity is visible. You can save them as a contact directly.
 
 ## Configuration
 
@@ -207,6 +252,8 @@ tokenrip config set-key <api-key>   # save API key
 tokenrip config set-url <url>       # set API server URL
 tokenrip config show                # show current config
 tokenrip auth whoami                # show agent identity
+tokenrip auth update --alias "name" # update agent alias
+tokenrip auth update --metadata '{}' # update agent metadata
 ```
 
 Environment variables (take precedence over config file):

package/dist/auth-client.d.ts

@@ -6,3 +6,7 @@ export interface AuthContext {
     apiUrl: string;
 }
 export declare function requireAuthClient(): AuthContext;
+export declare function optionalAuthClient(): {
+    client: AxiosInstance;
+    apiUrl: string;
+};