CLI reference

Core workflows are available from the CLI: connecting, evaluating, and rules. Install once:

npm install -g rippletide-package

Every command is then rippletide <command>, and all commands accept --json for machine-readable output.

Commands

Command	What it does
`login`	Log in via your browser; reuses a valid stored Platform key
`logout`	Revoke the current Platform key, then clear the local login
`whoami`	Show the logged-in account
`agents`	List the agents on your account
`connect [--yes]`	Create or link the current repository, write its CLI connection configuration, and present its setup prompt
`connect --print-prompt`	Create or link the repository, write its CLI connection configuration, and print the setup prompt for a coding agent
`verify`	Check a repository’s CLI configuration and synced inventory from its `.env` (no login needed)
`events --wait`	Wait for complete observed runtime evidence: manifest, heartbeat, and turn; MCP also needs a tool call
`status`	Auth, binding, inventory, worker, and evaluation readiness at a glance
`evaluate [--generate] [--wait]`	Start an evaluation run, optionally waiting for the result
`improve [--yes] [--wait]`	Propose and run an improvement loop (asks before running your agent)
`rules discover [--source <text\|https-url\|@file>]`	Review and batch-create complete discovered rules; `--json` is read-only
`rules create --target <id> --action <key> --input "…"`	Compile and save a disabled plain-English rule
`rules targets` / `rules list`	Inspect policy targets and rule releases
`rules decisions --agent <id> [--limit 20]`	Review recent decisions and get commands to enforce triggered observe releases
`rules set-mode --release <id> --mode disabled\|observe\|enforce`	Change one rule release’s mode

connect can execute your repository’s own rippletide:sync and rippletide:start scripts, so it asks for confirmation; pass --yes only for a repository you trust. It does not launch a coding agent or create those scripts for you. Apply the generated setup prompt in the coding agent you use for the repository. login validates ~/.rippletide/config.json before starting a browser flow, so running it again does not accumulate keys. To replace the key or change accounts, run rippletide logout and then rippletide login. A validation failure creates nothing, while a failed logout keeps the current local credential so revocation can be retried.

Where configuration lives

Scope	Path	Contents
Account	`~/.rippletide/config.json`	Endpoint and Platform key
Project	`.rippletide/project.json`	Agent ID and name (safe to commit)
Runtime	`.env`	`RIPPLETIDE` Connection string and `RIPPLETIDE_PROXY_URL` (never commit)

The CLI configuration is distinct from the app-based/manual configuration documented in API keys. Do not add RIPPLETIDE_AGENT_ID and RIPPLETIDE_API_KEY to a .env already managed by rippletide connect. After removing Rippletide instrumentation, disconnect a repository by deleting .rippletide/project.json, removing only RIPPLETIDE and RIPPLETIDE_PROXY_URL from .env, and revoking its Connection key in the Platform. rippletide logout is separate account-level cleanup: it revokes the CLI Platform key and clears the local account login.

Getting started

Connect

Rules

Observe

Improve

Reference

Commands

Where configuration lives

​Commands

​Where configuration lives

Commands

Where configuration lives