@rayrun/cli 0.1.0 → 0.4.0

package/README.md

@@ -1,6 +1,7 @@
 # @rayrun/cli
 
-Connect supported MCP clients to a Rayrun workspace endpoint without copying configuration by hand.
+Connect supported MCP clients, execute approved tools through OAuth, and manage Rayrun through its
+public API.
 
 ```sh
 pnpm --package @rayrun/cli@latest dlx rayrun setup https://copy-the-endpoint-from-rayrun.example/mcp
@@ -22,3 +23,91 @@ rayrun setup rollback <backup-id>
 Use `--project` for project-local configuration in Claude Code, Codex, Cursor, VS Code, Devin, and OpenCode. Legacy Windsurf remains user-scoped. Claude Code asks you to approve a project MCP server when that project opens. Codex loads `.codex/config.toml` only after you trust the project; restart Codex after doing so.
 
 Interactive setup runs supported clients' OAuth login commands. `--yes` and non-interactive setup never launch login unless you explicitly pass `--login`; the command prints the exact login command when it skips one. Pass `--no-login` to make the choice explicit in scripts.
+
+## Execute tools
+
+Execution commands connect to `https://ray.run/mcp/direct` and authenticate the person in a browser
+with OAuth. They do not use `RAYRUN_API_KEY`. Override the endpoint with `--endpoint` or
+`RAYRUN_MCP_URL` for a local or self-hosted Rayrun gateway.
+
+```sh
+rayrun tools describe linear.create_issue
+rayrun call linear.create_issue '{"title":"Fix the release"}'
+rayrun call linear.create_issue --input arguments.json
+```
+
+Tool names are service-qualified and must match the Direct Mode catalog exactly. Use `--input -` to
+read a JSON object from stdin, `--json` for machine-readable output, and `--no-open` to print browser
+URLs without launching them.
+
+If an exact call needs approval or a service authorization, the CLI opens the authenticated Rayrun
+page and saves a private continuation:
+
+```text
+Execution paused: 12345678-1234-1234-1234-123456789abc
+Resume: rayrun resume --execution-id 12345678-1234-1234-1234-123456789abc
+```
+
+Approve in the browser, then run the printed command. `resume` replays only the saved call with the
+server-issued continuation state; its `accept` response cannot authorize the call without the
+authenticated browser decision. Pending files can contain the exact tool arguments and are stored
+under `~/.rayrun/execution/pending`. The resume window expires after 10 minutes; expired files are
+pruned by the next execution command and are also removed by `rayrun logout`. OAuth refresh tokens
+use the same account-private storage. `RAYRUN_CONFIG_HOME` must use a local, per-host filesystem.
+POSIX systems enforce `0700` directories and `0600` files. On Windows, execution storage must remain
+inside the current user profile and inherits that profile's ACL. `logout` removes tokens locally and
+attempts token revocation.
+
+Execution lock errors print the exact generation file to remove if a process crashed and its PID was
+reused. Remove that file only after verifying that no Rayrun CLI execution command is still running.
+
+## Manage a workspace
+
+Create a scoped key in **Dashboard → Settings → API keys**, then export it without putting it in a
+command argument or configuration file. `RAYRUN_API_URL` is optional and defaults to
+`https://ray.run`.
+
+```sh
+export RAYRUN_API_KEY='rak_...'
+
+rayrun connect mcp https://mcp.example.com --name 'Internal tools'
+rayrun connect openapi https://api.example.com/openapi.json --name 'Example API'
+rayrun connections list
+rayrun clients list
+rayrun tools search create issue --connection <connection-uid>
+rayrun policy inspect <client-uid> --query issue
+rayrun approvals list
+rayrun activity list
+```
+
+List commands show a compact table. Add `--json` for stable machine-readable output, `--limit` to
+request up to 100 rows, and `--cursor` with the printed next cursor to continue. The CLI calls the
+same hosted API and policy evaluator as the dashboard; it does not run a local gateway or store API
+keys.
+
+## Author hosted tool hooks
+
+Use a full-control API key. Hook source executes in Rayrun’s hosted sandbox, not in the CLI process.
+
+```sh
+rayrun hooks pull <connection-uid> <tool-uid> \
+  --output hook.ts --types-output rayrun-hooks.d.ts
+
+rayrun hooks test <connection-uid> <tool-uid> \
+  --file hook.ts --arguments '{"query":"release"}' --mock-result '{"items":[]}'
+
+rayrun hooks deploy <connection-uid> <tool-uid> --file hook.ts --shadow
+rayrun hooks logs <connection-uid> <tool-uid>
+rayrun hooks rollback <connection-uid> <tool-uid> <revision-uid>
+rayrun hooks deactivate <connection-uid> <tool-uid> --shadow
+```
+
+`pull` can write the draft and generated TypeScript declarations separately. `test` compiles and
+runs before plus an optional after stage using your mock result; it never contacts the upstream.
+`deploy` saves `--file` and optional `--config` before creating an immutable revision. Omit `--shadow`
+to deploy active. Rollback and deactivate default to active and accept `--shadow` for the shadow
+pointer. Hook log payloads appear only when the service’s payload-capture setting is enabled; timing,
+outcome, revision, request correlation, and the shadow changed/unchanged signal remain available
+either way. Captured messages, structured data, and errors require a full-control key. Use
+`hooks logs --json` for the full-fidelity retained record. Compiler errors include hook.ts line and
+column diagnostics.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rayrun/cli",
-  "version": "0.1.0",
-  "description": "Safely connect local MCP clients to Rayrun",
+  "version": "0.4.0",
+  "description": "Set up MCP clients, execute tools, and manage Rayrun from the command line",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -15,7 +15,10 @@
     "index.js",
     "src/clients.js",
     "src/config.js",
+    "src/execution.js",
     "src/main.js",
+    "src/management.js",
+    "src/oauth.js",
     "src/setup.js",
     "README.md",
     "LICENSE"
@@ -24,10 +27,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "test": "vitest run"
-  },
   "dependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
+    "@rayrun/sdk": "^0.5.0",
     "jsonc-parser": "^3.3.1",
     "smol-toml": "^1.8.0"
   },
@@ -36,5 +38,8 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "scripts": {
+    "test": "vitest run"
   }
-}
+}