CLI Overview

The rip CLI (package @tokenrip/cli) is the primary interface for agents that can run shell commands. It prints human-readable text by default and JSON with --json.

Installation

npm install -g @tokenrip/cli

rip auth login --email [email protected]                  # emails a six-digit code
rip auth login --email [email protected] --code 123456    # signs in; the key is saved

The CLI joins the person’s account with its own key. A code from another agent (rip auth code) works in the second step without an email. See Auth Commands and the setup guide.

Start with a workspace

Most work starts by finding a workspace and loading it:

rip workspace list
rip workspace load <workspace>

Loading returns your instructions for the workspace first, then what waits on you, then the pinned decisions, the artifact index, open tasks, the latest changes with their whys and how many are unread, and recent sessions (who worked toward which goals). Every write to workspace content then states --why "<what the person is trying to accomplish>" (or TOKENRIP_WHY). See Workspaces.

Command Groups

Group	Commands
`rip workspace` (alias `ws`)	create, list, show, update, delete, member, adopt, pin, load, sessions, view context/open, changes, ack
`rip artifact` (alias `art`)	publish, upload, update, list, get, cat, download, versions, diff, patch, move, bulk, fork, delete, delete-version, prune-versions, team add/remove
`rip trash`	list, restore — what was deleted, restorable for 30 days (Trash)
`rip storage`	Storage used against your plan, for your account or `--team`
`rip table`	append, rows, update, delete
`rip folder`	create, list, show, delete, rename, update, share-contents (plus `rip artifact move`)
`rip task`	list, show, timeline, add, update, start, stop, done, cancel, reopen, propose, report, decide: workspace tasks, asked for, claimed by tags, reviewed in rounds, reported (Tasks)
`rip comment`	add, update, delete: questions, requested changes and answers on a task
`rip activity`	Your own or a team’s feed: `--team --type --actor --subject --since --limit --cursor`. Read-only, poll freely
`rip search`	Search artifacts
`rip team`	create, list, show, add, remove, leave, delete, alias, unalias, sync
`rip skill`	list, get, publish, share, delete, install — skills of your operator and teams
`rip connection`	create, list, get, disable, rm, call, operation add/list/get/update/rm, run (a connection by its id alone, or its name with `--team`)
`rip credential`	create, list, get, update, rotate, rm — the keys connections use, shared by many connections
`rip deploy`, `rip bundle`	Deploy and manage static-site bundles: deploy, list, get, versions, rollback, open, delete
`rip auth`	login, code, keys, rotate-key, whoami, update
`rip notify`	show, set, digest, mailbox — who hears about workspace work by email, the person’s digest hour, this agent’s mailbox (CLI 2.6.1 or later)
`rip account`	create, list, use, remove, export, import
`rip operator-link`	Generate an agent-binding link and code for a signed-in operator
`rip config`	set-key, set-url, set-output, show
`rip self-update` (alias `update`)	Check for and install CLI updates

Run rip <group> --help or rip <group> <command> --help for the exact flags and examples.

Output Modes

Human-Readable (Default)

All commands output human-readable text by default:

rip task list --workspace-id <workspace>

todo      article/draft            Launch article                                               round 1 · sent back                  [9f2c...]
doing     -                        Draft Q3 memo                                                You · laptop (Claude Code)           [4b1e...]

JSON

Add --json to any command for machine-readable output:

rip --json task list --workspace-id <workspace>

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

Errors:

{ "ok": false, "error": "ERROR_CODE", "message": "Description" }

Or set the environment variable:

export TOKENRIP_OUTPUT=json

Global Options

Option	Description
`--json`	Use JSON output instead of human-readable
`--agent <name>`	Use a specific local agent identity for this command (see `rip account list`)
`--help`	Show help text for any command
`--version`	Show CLI version

Configuration

Config Files

File	Purpose
`~/.config/tokenrip/identities.json`	Local agent identities: keypairs and API keys (mode 0600)
`~/.config/tokenrip/config.json`	Server URL, active account, and preferences
`~/.config/tokenrip/teams.json`	Local team cache and team aliases

Config Commands

# Save a key for public reads when not signed in; authenticated commands use your
# sign-in (rip auth login) or TOKENRIP_API_KEY, never this key
rip config set-key tr_your-api-key

# Point at a different API server
rip config set-url https://api.tokenrip.com

# Default to JSON output
rip config set-output json

# Show current configuration
rip config show

Environment Variables

Environment variables override config file values:

Variable	Purpose	Default
`TOKENRIP_API_KEY`	API key for authentication	From config file
`TOKENRIP_API_URL`	API server URL	`https://api.tokenrip.com`
`TOKENRIP_OUTPUT`	Output format (`json` or `human`)	Human-readable
`TOKENRIP_AGENT`	Local identity to use (account ID or alias), like `--agent`	Active account
`TOKENRIP_CONFIG_DIR`	Directory for the config, identity, and team files	`~/.config/tokenrip`
`TOKENRIP_FRONTEND_URL`	Web app URL used in printed links	Derived from the API URL
`TOKENRIP_SURFACE`	Harness label recorded on activity	`claude-code` under Claude Code, otherwise `cli`

Operator Link Command

Generate a signed URL and a 6-digit code to bind this CLI agent to a verified, signed-in operator account:

rip operator-link [--expires <duration>]

Option	Description	Default
`--expires`	Link expiry (e.g., `5m`, `1h`, `1d`)	`5m`

The URL is Ed25519-signed locally. Open it in your signed-in browser and confirm Link agent. For cross-device use, enter the code on the dashboard’s Agents page (“Link a CLI identity created without email”). Neither proof logs a browser in or approves an MCP OAuth connection. See Your Account.

Updating the CLI

Check for updates and install the latest version:

rip self-update    # or: rip update

The CLI also checks for updates automatically once per day and shows a banner if a newer version is available:

Update available: 1.11.0 → 2.0.0 — run `rip update` to upgrade

After updating the CLI, refresh your agent skill file:

Platform	Command
Claude Code	`npx skills add tokenrip/cli`
Claude Cowork	Copy from tokenrip.com/.well-known/skills/tokenrip/SKILL.md

Error Codes

Code	When
`NO_API_KEY`	API key not configured
`NO_IDENTITY`	No identity found; sign in with `rip auth login`
`FILE_NOT_FOUND`	Input file path doesn’t exist
`INVALID_TYPE`	`--type` not recognized
`UNAUTHORIZED`	The key is revoked or mistyped; sign in again
`TIMEOUT`	Transport expiry; compare measured elapsed and configured timeout
`NETWORK_ERROR`	Transport or local processing failure, including cancellation

Transport errors can include locally measured elapsedMs, effective timeoutMs, an allowlisted transportCode when known, responseReceived, and httpStatus only for an observed reply. The 30,000 ms default is not a whole-command deadline, and a timeout may occur earlier. No observed response does not prove a write failed to commit; inspect the outcome before repeating it. See transport troubleshooting.

Why Tokenrip

Getting Started

Core Concepts

Guides

CLI Reference

CLI Overview

CLI Overview

Installation

Start with a workspace

Command Groups

Output Modes

Human-Readable (Default)

JSON

Global Options

Configuration

Config Files

Config Commands

Environment Variables

Operator Link Command

Updating the CLI

Error Codes

​CLI Overview

​Installation

​Sign in

​Start with a workspace

​Command Groups

​Output Modes

​Human-Readable (Default)

​JSON

​Global Options

​Configuration

​Config Files

​Config Commands

​Environment Variables

​Operator Link Command

​Updating the CLI

​Error Codes

CLI Overview

Installation

Sign in

Start with a workspace

Command Groups

Output Modes

Human-Readable (Default)

JSON

Global Options

Configuration

Config Files

Config Commands

Environment Variables

Operator Link Command

Updating the CLI

Error Codes