@ory/cline 0.11.1 → 0.12.0

package/README.md

@@ -1,112 +1,136 @@
 # Ory Agent Plugin: Cline
 
-[Ory](https://ory.com) bundled into [Cline](https://github.com/cline/cline): skills that scaffold Ory authentication into your codebase, a local Ory stack you can spin up in one command, and (when pointed at an Ory project) authentication, authorization, and audit for every tool Cline runs.
+Security and developer experience for [Cline](https://github.com/cline/cline), powered by [Ory](https://ory.com).
 
-You don't need an Ory account or any prior Ory experience to start.
+**Security.** Cline runs real actions on your machine — editing files, running shell commands, calling APIs. The plugin gives every session a verifiable identity (you sign in once; Cline and any sub-agents it spawns each get their own), checks every tool call against permissions you control, and records each decision as an audit trace you can ship to your observability stack. It starts in watch mode so nothing is blocked on day one, and if Ory is ever unreachable it steps aside rather than locking you out.
 
-This integration uses Cline's **file-based hooks** (not the in-process SDK) and is verified against cline@3.0.29.
+**Developer experience.** A single command installs the plugin and walks you through connecting — choose Ory Network, a local Docker stack, or audit-only, and it wires up the project, sign-in client, login, and permissions for you. It also helps you build Ory into your own app: ask in plain language to scaffold login, registration, and recovery pages, run a local Ory, or manage identities and permissions through the bundled MCP server.
 
-## New to Ory?
+## What you'll need
 
-[Ory](https://www.ory.com/docs/) is an open-source identity and access platform — login, registration, sessions, social sign-in, multi-factor auth, and fine-grained permissions, so you don't have to build any of that yourself. Two things make it easy to try with no prior experience:
+- [Cline](https://github.com/cline/cline), installed (verified against cline@3.0.29)
+- Node.js **22 or newer**
+- [Docker](https://docs.docker.com/get-docker/) — only if you want to run Ory locally
+- macOS or Linux (Windows works via WSL2)
 
-- **Ory Elements** are prebuilt, themeable UI components for the auth pages. The scaffolding skills wire them into your app for you.
-- **The local Ory stack** is a complete Ory running on your laptop in Docker — no account, no signup, no API key.
+## Get started
 
-## What this plugin does
+Run one command. It installs the plugin and walks you through connecting:
 
-Two independent things, and you can use either on its own:
-
-1. **Build auth into your app.** Have Cline scaffold Ory login, registration, social sign-in, and permissions into the project you're working on, backed by the local stack. This needs nothing but Docker.
-2. **Govern the agent itself.** Authenticate Cline's own session and authorize every tool it runs against Ory Permissions, with a full audit trail. See [Agent security](#agent-security).
+```bash
+npx -y -p @ory/cline ory-cline install
+```
 
-## Prerequisites
+You'll be asked how you want to connect — **press Enter for the default**:
 
-- [Cline](https://github.com/cline/cline) installed
-- Node.js **≥ 22**
-- [Docker](https://docs.docker.com/get-docker/) (only needed for the local Ory stack)
-- macOS or Linux. Windows works via WSL2.
+- **Ory Network** *(default)* — sign in, or create a free account, in your browser. The project, keys, permissions, and login are all set up for you. Nothing to configure by hand.
+- **Local** — run a complete Ory on your laptop with Docker. No account, no signup, no keys. Great for trying it out.
+- **Audit-only** — skip Ory entirely and just log what Cline does.
 
-## Install
+That's it. Confirm everything landed with:
 
 ```bash
-npx -y -p @ory/cline ory-cline install
+npx -y -p @ory/cline ory-cline status
 ```
 
-Cline discovers hooks by directory — the presence of an executable script named after the event *is* the registration. `install` writes one thin shell shim per event into the workspace hooks directory `<project>/.clinerules/hooks/` (or `~/.cline/hooks/` with `--global`), `chmod 0755`s each, and materializes the Ory skills. Each shim execs the published hook binary via `npx`.
+`status` is your one-stop check: what's configured, who's signed in, which tools are covered by permissions, and recent activity. Anything not set up yet shows as `(unset)`.
 
-```bash
-npx -y -p @ory/cline ory-cline install --global   # install for all projects
-npx -y -p @ory/cline ory-cline status              # confirm what landed
-npx -y -p @ory/cline ory-cline uninstall           # remove only the Ory shims + skills
-```
+> Re-run install with `--reconfigure` to change your connection later, or `--no-configure` to skip the wizard and configure by hand. Add `--global` to install for every project (`~/.cline/hooks/`) instead of just this one.
 
-Install and uninstall both respect hook scripts you authored. If an event name is already taken by a script the Ory installer didn't write (matched by a marker comment), install leaves it untouched, skips that event, and prints a warning listing the skipped events — move or remove your script and re-run the install if you want Ory to handle them. Existing Ory shims are refreshed in place, and uninstall removes only the scripts the Ory installer wrote.
+## What you get
 
-## Quickstart (≈ 3 minutes)
+Once connected, every task and tool call Cline runs is governed by Ory — three things happen automatically:
 
-From any project where you'd like Ory authentication, inside Cline:
+- **Who's driving.** You sign in once in your browser; Cline gets its own identity too, and registers it automatically on first run — no tokens to copy around. The "who acted on whose behalf" trail stays queryable later.
+- **What it's allowed to do.** Before a tool runs, Ory checks whether it's permitted. It starts in **watch mode** — nothing is blocked, you just *see* what would be — so it never gets in your way on day one.
+- **A record of everything.** Every decision (allowed, denied, skipped) is logged as a trace you can send to Jaeger, Honeycomb, Grafana, or just a file.
 
-1. **Start a local Ory instance.** Ask Cline *"start the local Ory stack"* or invoke the `ory-local-up` skill. A banner prints the seeded test user's email and password — note them.
-2. **Scaffold Ory into your project.** Ask Cline *"add Ory auth to this app"* (the `ory-auth-setup` skill). It installs Ory Elements, wires the SDK, and generates the login / registration / recovery / settings pages, all targeting the local stack.
-3. **Sign in.** Start your app, visit the login page, and sign in with the seeded credentials. You now have a real Ory session backed by a real Ory stack — locally, offline, zero configuration.
+If Ory is ever unreachable, the plugin gets out of the way and lets Cline keep working — so it can't lock you out.
 
-Continue to [Agent security](#agent-security) when you're ready to enforce.
+### See what's happening
 
-## How the integration works
+Everything the plugin does is observable out of the box — no configuration required:
 
-Cline runs each hook script as a **subprocess**, passing the event payload as JSON on stdin and reading a JSON decision on stdout. A hook blocks a tool call by returning `{"cancel":true}`. Cline does **not** expose a separate approval-ask hook, so the plugin gates at the tool-call event. Hooks have a 30-second timeout.
+- **Status at a glance.** `npx -y -p @ory/cline ory-cline status` shows what's configured, who's signed in, how many built-in tools your permissions cover, and the most recent tool-call activity.
+- **Live traces.** Every tool call is recorded as an OpenTelemetry-style span. Watch them stream as the agent works:
 
-The hook script filenames are PascalCase (`TaskStart`, `PreToolUse`, …); the payload Cline delivers on stdin carries the matching snake_case event name (`agent_start`, `tool_call`, …) the plugin acts on. The shims wire into these phases:
+  ```bash
+  npx -y -p @ory/cline ory-cline watch
+  ```
 
-- **TaskStart** (`agent_start`) — run the user and agent auth gates.
-- **PreToolUse** (`tool_call`) — check the tool against Ory Permissions; deny blocks the call (`{"cancel":true}`) in enforce mode.
-- **PostToolUse / TaskComplete / TaskCancel / TaskError / UserPromptSubmit / PreCompact / SessionShutdown** — trace-only audit spans.
+  Spans are also written to `~/.config/ory-agent-plugins/cline/ory-agent-trace.ndjson` (NDJSON, one span per line) — tail that file, or point `OTEL_EXPORTER_OTLP_ENDPOINT` at a collector to ship them straight to Jaeger, Honeycomb, or Grafana.
+- **Debug log.** For a verbose play-by-play, set `ORY_AGENT_DEBUG=true`; structured logs land in `~/.config/ory-agent-plugins/cline/ory-agent-debug.log`.
 
-The plugin is **fail-open** on its own infrastructure failures (network errors, rate limits, missing config): the agent always starts, and enforcement is only as strong as your permission grants.
+### Ready to enforce?
 
-## Agent security
+When the watch-mode logs look right, turn on blocking with one command (setup already granted you the built-in tools):
 
-Once pointed at an Ory project (local or hosted), Cline's task and every tool call can be governed by Ory.
+```bash
+npx -y -p @ory/cline ory-cline permissions enforce
+```
 
-- **Authentication.** The human at the keyboard (the **user**) authenticates interactively via Ory Identities when user login is on (`ORY_USER_LOGIN=true`, off by default — browser PKCE flow on first session, persisted thereafter). The Cline process (the **agent**) gets its own OAuth2 identity via [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) on first run.
-- **Authorization.** Before any tool runs, the plugin checks [Ory Permissions](https://www.ory.com/docs/keto) (Zanzibar-style relations) against the user's subject and blocks on `deny`.
-- **Audit.** Every decision is recorded as a structured trace span (NDJSON file and/or OTLP export).
+Now a denied tool is actually blocked and Cline shows why. Go back to watch mode anytime with `permissions observe`. Use `permissions status` to see what's covered and `permissions bootstrap` to (re-)grant the built-in tools.
 
-### Permission modes: observe → enforce
+## Also: add login to your own app
 
-After install the plugin runs in **observe mode**: every tool call is checked, but a deny is recorded as a `permission.observe_deny` audit span and the tool runs anyway.
+Beyond securing Cline, the plugin helps you build Ory into whatever you're working on. Ask Cline *"add Ory login to this app"* and it scaffolds the login, registration, recovery, and settings pages (using [Ory Elements](https://github.com/ory/elements)) wired to a local Ory — no signup or keys needed. These are **skills**: just ask in plain language and the matching one takes over.
 
-```bash
-# Grant the current user `use` on every built-in tool (idempotent):
-npx -y -p @ory/cline ory-cline permissions bootstrap
+Start that local Ory with the `ory-local-up` skill (it prints a test email + password to sign in with) and tear it down with `ory-local-down`. It runs the Ory APIs at `http://localhost:4000`, a login UI on `:4455` (not :3000, to avoid Next.js port conflicts), the Ory Console on `:4100`, and Jaeger on `:16686`. More bundled skills cover login flows, social sign-in (Google, GitHub, Apple…), permissions onboarding, and playbooks for wiring Ory into your own agents, E2B sandboxes, or Temporal workers.
 
-# See allowed/denied per tool:
-npx -y -p @ory/cline ory-cline permissions status
+## Configure by hand (CI / advanced)
 
-# Turn on hard blocking once the observe-mode logs look right:
-npx -y -p @ory/cline ory-cline permissions enforce
+The guided setup covers most people. For scripted or CI setups, or to point at an existing Ory Network project, configure directly. Settings are saved to `~/.config/ory-agent-plugins/config.json` and shared across all your Ory agent plugins; environment variables win when both are set.
+
+```bash
+npx -y -p @ory/cline ory-cline configure \
+  --project-url https://<slug>.projects.oryapis.com \
+  --oauth2-client-id <sign-in client id> \
+  --user-login
 ```
 
-Switch back any time with `permissions observe`. To disable Ory entirely (audit logging only), run `ory-cline configure --audit-only`.
+Cline's own identity registers itself automatically on first run — nothing to create. The `--oauth2-client-id` is the one piece browser sign-in needs (a **public sign-in client** registered with the loopback URLs `http://127.0.0.1:47823..47826/callback`); the guided setup makes it for you. For logging-only with no checks, use `--audit-only`. Enable browser sign-in persistently with `--user-login`, or per-session with `ORY_USER_LOGIN=true` (the env var overrides the saved config).
 
-## Pointing at a real Ory project
+With nothing configured, the plugin still loads and runs in **pass-through mode**: skills and logging work, but no checks run and nothing is blocked. Perfectly fine if you only want the app-building features.
 
-The Quickstart uses the local stack. To point at a hosted [Ory Network](https://console.ory.sh) project:
+<details>
+<summary>How the integration works</summary>
 
-```bash
-npx -y -p @ory/cline ory-cline configure \
-  --project-url https://<id>.projects.oryapis.com \
-  --oauth2-client-id <public OAuth2 client id>
+Cline discovers hooks by directory — the presence of an executable script named after the event *is* the registration. `install` writes one thin shell shim per event into the workspace hooks directory `<project>/.clinerules/hooks/` (or `~/.cline/hooks/` with `--global`), makes each executable, and materializes the Ory skills. Each shim execs the published hook binary via `npx`. Install and uninstall respect hook scripts you authored: if an event name is already taken by a script Ory didn't write, install skips it and prints a warning; uninstall removes only the scripts Ory wrote.
+
+Cline runs each hook as a **subprocess**, passing the event as JSON on stdin and reading a JSON decision on stdout. A hook blocks a tool call by returning `{"cancel":true}`. Cline does **not** expose a separate approval-ask hook, so the plugin gates at the tool-call event. Hooks have a 30-second timeout.
+
+The hook filenames are PascalCase (`TaskStart`, `PreToolUse`, …); the payload Cline delivers carries the matching snake_case event name (`agent_start`, `tool_call`, …) the plugin acts on. The shims wire into these phases:
+
+- **TaskStart** (`agent_start`) — signs the user in and gives Cline its identity.
+- **PreToolUse** (`tool_call`) — checks the tool against your permissions; a deny blocks the call in enforce mode.
+- **PostToolUse / TaskComplete / TaskCancel / TaskError / UserPromptSubmit / PreCompact / SessionShutdown** — audit-only trace spans.
+
+</details>
+
+## Commands
+
+```
+ory-cline install | uninstall        Install/remove; --global for all projects, --reconfigure re-runs setup, --no-configure skips it
+ory-cline status                     Show configuration, identities, permission coverage, recent activity
+ory-cline watch                      Tail the live trace stream (OTel spans)
+ory-cline permissions <cmd>          status | bootstrap | observe (watch) | enforce (block)
+ory-cline configure <flags>          Point at a project by hand (--project-url, --oauth2-client-id, --user-login, --audit-only)
+ory-cline agent <status|unregister>  Manage Cline's own auto-created identity
 ```
 
-`--oauth2-client-id` is required whenever `--project-url` is set — the user PKCE flow needs a public OAuth2 client registered with the four loopback redirect URIs (`http://127.0.0.1:47823..47826/callback`). See the [repo README](../../README.md) and [`AGENTS.md`](../../AGENTS.md) for the full environment-variable reference and permission-mode semantics. Config is shared across every Ory agent plugin at `~/.config/ory-agent-plugins/config.json`.
+All prefixed with `npx -y -p @ory/cline`.
+
+## Troubleshooting
 
-Without configuration the plugin still loads cleanly and runs in **pass-through mode**: skills work, but nothing is blocked.
+- **Local Ory fails to start** — make sure Docker is running and ports `4000`, `4100`, `4455`, and `16686` are free.
+- **Browser sign-in loops** — reset with `ory-cline agent unregister` and try again.
+- **`npx` grabbed an old version** — force the latest: `npx -y -p @ory/cline@latest ory-cline …`.
+- **A hook didn't install** — check the install output for a skipped-event warning; move or remove your own script at that event name and re-run install.
+- **Want to see what's happening** — `npx -y -p @ory/cline ory-cline status` for a snapshot, `npx -y -p @ory/cline ory-cline watch` for the live trace stream, or set `ORY_AGENT_DEBUG=true` for a verbose log. Traces and logs live under `~/.config/ory-agent-plugins/cline/` (see [See what's happening](#see-whats-happening)).
 
-## Links
+## Learn more
 
-- [Ory documentation](https://www.ory.com/docs/)
+- [Ory documentation](https://www.ory.com/docs/) · [Ory Console](https://console.ory.sh) · [Ory Elements](https://github.com/ory/elements)
 - [Cline repository](https://github.com/cline/cline)
 - [Repo README](../../README.md) and [AGENTS.md](../../AGENTS.md) — full env-var and permission-mode reference
 

package/dist/cli/main.js

@@ -56,14 +56,19 @@ function main() {
     const [command, ...args] = process.argv.slice(2);
     switch (command) {
         case "install":
+            (0, argus_1.beginDeferNextSteps)();
             install(args);
-            postInstallPermissions("ory-cline", "cline").then(() => process.exit(0), (err) => {
+            (0, argus_1.runPostInstall)("ory-cline", "cline", args).then(() => process.exit(0), (err) => {
                 console.error(err.message ?? err);
                 process.exit(1);
             });
             break;
         case "uninstall":
             uninstall(args);
+            (0, argus_1.clearCredentialsForUninstall)().then(() => process.exit(0), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
             break;
         case "configure":
             (0, argus_1.runConfigureCommand)("ory-cline", args);
@@ -95,6 +100,9 @@ function main() {
                 process.exit(1);
             });
             break;
+        case "watch":
+            (0, argus_1.runWatchCommand)("cline", args);
+            break;
         case "help":
         case "--help":
         case "-h":
@@ -125,12 +133,6 @@ function runSetup(args) {
     process.argv = ["node", "setup.js", ...args];
     require("./setup.js");
 }
-async function postInstallPermissions(binName, harness) {
-    const bootstrapped = await (0, argus_1.maybeAutoBootstrap)(binName, harness);
-    (0, argus_1.printPermissionsOnboardingHelp)(binName, harness, {
-        bootstrappedAutomatically: bootstrapped,
-    });
-}
 async function status() {
     await (0, argus_1.runStatusCommand)("ory-cline", "cline", {
         title: "Cline",
@@ -149,7 +151,7 @@ function help() {
 ory-cline — Ory plugin for Cline
 
 Usage:
-  npx ory-cline <command> [options]
+  npx -y -p @ory/cline ory-cline <command> [options]
 
 Commands:
   install [--global]     Install the Ory hook scripts into Cline
@@ -159,6 +161,7 @@ Commands:
   permissions <cmd>      Manage permission mode and tool permissions (status, bootstrap, observe, enforce)
   setup [options]        Write hook scripts directly to the hooks directory (fallback)
   status                 Show plugin status and configuration
+  watch [trace-file]     Tail the trace stream (OTel spans) live
   local <cmd>            Manage local Ory dev environment (up, down, status, seed, ...)
 
 After installing, the per-event hook scripts wire into these Cline lifecycle events:
@@ -167,10 +170,10 @@ After installing, the per-event hook scripts wire into these Cline lifecycle eve
   PostToolUse            Audit log tool executions
 
 Examples:
-  npx ory-cline install             # Install hook scripts into ./.clinerules/hooks
-  npx ory-cline install --global    # Install into ~/.cline/hooks
-  npx ory-cline status              # Check configuration
-  npx ory-cline uninstall           # Remove hook scripts
+  npx -y -p @ory/cline ory-cline install             # Install hook scripts into ./.clinerules/hooks
+  npx -y -p @ory/cline ory-cline install --global    # Install into ~/.cline/hooks
+  npx -y -p @ory/cline ory-cline status              # Check configuration
+  npx -y -p @ory/cline ory-cline uninstall           # Remove hook scripts
 `);
 }
 main();

package/dist/cli/setup.js

@@ -170,6 +170,18 @@ function main() {
         console.warn("");
     }
     console.log(`Ory skills installed to ${path.join(rulesRoot, "skills")}`);
-    (0, argus_1.printNextSteps)("Cline", "npx ory-cline-setup --uninstall");
+    (0, argus_1.printNextSteps)("Cline", "npx -y -p @ory/cline ory-cline-setup --uninstall", {
+        binName: "ory-cline",
+        harness: "cline",
+    });
 }
 main();
+// When invoked directly as the `-setup` bin with `--uninstall`, also clear
+// stored Ory credentials. When required by the plugin's main CLI, that
+// command owns the purge, so the `require.main` guard prevents a double run.
+if (require.main === module && process.argv.includes("--uninstall")) {
+    (0, argus_1.clearCredentialsForUninstall)().then(() => process.exit(0), (err) => {
+        console.error(err.message ?? err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/cline",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Ory plugin for Cline: scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",
@@ -66,7 +66,7 @@
     "!dist/**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@ory/argus": "0.11.1"
+    "@ory/argus": "0.12.0"
   },
   "devDependencies": {
     "typescript": "^6.0.2",