@ory/gemini-cli 0.11.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +72 -199
  2. package/dist/cli/main.js +15 -12
  3. package/dist/cli/setup.js +13 -1
  4. package/package.json +2 -2
package/README.md CHANGED
@@ -1,168 +1,108 @@
1
1
  # Ory Agent Extension: Gemini CLI
2
2
 
3
- [Ory](https://ory.com) bundled into [Gemini CLI](https://github.com/google-gemini/gemini-cli): skills and TOML slash commands 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 Gemini runs.
3
+ Security and developer experience for [Gemini CLI](https://github.com/google-gemini/gemini-cli), powered by [Ory](https://ory.com).
4
4
 
5
- You don't need an Ory account or any prior Ory experience to start.
5
+ **Security.** Gemini runs real actions on your machine — editing files, running shell commands, calling APIs. The extension gives every session a verifiable identity (you sign in once; Gemini 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.
6
6
 
7
- ## New to Ory?
7
+ **Developer experience.** A single command installs the extension 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.
8
8
 
9
- [Ory](https://www.ory.com/docs/) is an open-source identity and access platform — it provides 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:
9
+ ## What you'll need
10
10
 
11
- - **Ory Elements** are prebuilt, themeable UI components for the auth pages (login, registration, recovery, settings). The scaffolding skills wire them into your app for you.
12
- - **The local Ory stack** is a complete Ory running on your laptop in Docker — no account, no signup, no API key. Everything in the Quickstart below works against it, fully offline.
11
+ - [Gemini CLI](https://github.com/google-gemini/gemini-cli), installed and signed in
12
+ - Node.js **22 or newer**
13
+ - [Docker](https://docs.docker.com/get-docker/) — only if you want to run Ory locally
14
+ - macOS or Linux (Windows works via WSL2)
13
15
 
14
- This extension does two independent things, and you can use either on its own:
16
+ ## Get started
15
17
 
16
- 1. **Build auth into your app.** Have Gemini scaffold Ory login, registration, social sign-in, and permissions into the project you're working on, backed by the local stack. This is the Quickstart below — it needs nothing but Docker.
17
- 2. **Govern the agent itself.** Authenticate Gemini's own session and authorize every tool it runs against Ory Permissions, with a full audit trail. See [Agent security](#agent-security).
18
-
19
- If you're just exploring, do the Quickstart first.
20
-
21
- ## Prerequisites
22
-
23
- - [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and signed in
24
- - Node.js **≥ 22**
25
- - [Docker](https://docs.docker.com/get-docker/) (only needed for the local Ory stack)
26
- - macOS or Linux. Windows works via WSL2.
27
-
28
- ## Install
29
-
30
- In your shell:
18
+ Run one command. It installs the extension and walks you through connecting:
31
19
 
32
20
  ```bash
33
- gemini extensions install https://github.com/ory/gemini-cli-extension
21
+ npx -y -p @ory/gemini-cli ory-gemini install
34
22
  ```
35
23
 
36
- Then confirm everything landed:
24
+ This registers the extension — its hooks, skills, `/ory:` slash commands, and the bundled Ory MCP server — then asks how you want to connect. **Press Enter for the default**:
37
25
 
38
- ```bash
39
- npx -y -p @ory/gemini-cli ory-gemini status
40
- ```
26
+ - **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.
27
+ - **Local** — run a complete Ory on your laptop with Docker. No account, no signup, no keys. Great for trying it out.
28
+ - **Audit-only** — skip Ory entirely and just log what Gemini does.
41
29
 
42
- `status` is the single source of truth — it prints configuration, user and agent identity, per-tool permission coverage, extension + skill registration, and a tail of recent debug logs. Unconfigured fields show inline as `(unset)`.
43
-
44
- <details>
45
- <summary>Alternative install paths</summary>
30
+ That's it. Confirm everything landed with:
46
31
 
47
32
  ```bash
48
- npx -y -p @ory/gemini-cli ory-gemini install
49
- npx -y -p @ory/gemini-cli ory-gemini uninstall
33
+ npx -y -p @ory/gemini-cli ory-gemini status
50
34
  ```
51
35
 
52
- If the `gemini` binary isn't on your `PATH`, `npx -y -p @ory/gemini-cli ory-gemini-setup` writes the extension config directly into your project's `.gemini/settings.json`.
53
-
54
- </details>
55
-
56
- ## Quickstart (≈ 3 minutes)
57
-
58
- From any project where you'd like Ory authentication, inside Gemini CLI:
36
+ `status` is your one-stop check: what's configured, who's signed in, which tools are covered by permissions, whether the extension and skills registered, and recent activity. Anything not set up yet shows as `(unset)`.
59
37
 
60
- 1. **Start a local Ory instance.** Ask Gemini *"start the local Ory stack"* or run:
38
+ > Prefer to install the extension natively? Run `gemini extensions install https://github.com/ory/gemini-cli-extension`. That registers the extension but skips the guided setup — run `ory-gemini install` (or `configure`) in a terminal afterwards to connect. Re-run install with `--reconfigure` to change your connection later, or `--no-configure` to skip the wizard. If the `gemini` binary isn't on your `PATH`, `npx -y -p @ory/gemini-cli ory-gemini-setup` writes the extension config straight into your project's `.gemini/settings.json`.
61
39
 
62
- ```
63
- /ory:local-up
64
- ```
40
+ ## What you get
65
41
 
66
- A banner prints the seeded test user's email and password. Note them — you'll log in with them in step 3.
42
+ Once connected, every tool Gemini runs is governed by Ory — three things happen automatically:
67
43
 
68
- 2. **Scaffold Ory into your project.** Ask Gemini *"add Ory auth to this app"* or invoke the `ory-auth-setup` skill.
44
+ - **Who's driving.** You sign in once in your browser; Gemini 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.
45
+ - **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.
46
+ - **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.
69
47
 
70
- Gemini installs Ory Elements, wires the SDK, generates the login / registration / recovery / verification / settings pages, and sets up session middleware. It targets the local stack from step 1, so no signup or API key is needed.
48
+ If Ory is ever unreachable, the extension gets out of the way and lets Gemini keep working — so it can't lock you out.
71
49
 
72
- 3. **Sign in.** Start your app, visit the login page Gemini added, and sign in with the seeded credentials. You now have a real Ory session backed by a real Ory stack — locally, offline, with zero configuration.
50
+ ### See what's happening
73
51
 
74
- 4. **Turn on Ory login for the Gemini session itself.** *(Optional but recommended.)* Out of the box the extension only governs your *app*. To also attach an Ory identity to *Gemini's* session — so every tool call is attributed to you, not a fallback `session:<id>` subject — opt in to the user-login flow:
52
+ Everything the plugin does is observable out of the box — no configuration required:
75
53
 
76
- ```bash
77
- export ORY_USER_LOGIN=true
78
- export ORY_OAUTH2_CLIENT_ID=<value printed by `local up`>
79
- ```
54
+ - **Status at a glance.** `npx -y -p @ory/gemini-cli ory-gemini status` shows what's configured, who's signed in, how many built-in tools your permissions cover, and the most recent tool-call activity.
55
+ - **Live traces.** Every tool call is recorded as an OpenTelemetry-style span. Watch them stream as the agent works:
80
56
 
81
- User login is off by default. Both exports above are printed in the `local up` banner — copy them straight from there. `ORY_OAUTH2_CLIENT_ID` is required whenever `ORY_USER_LOGIN` is on: it identifies the public OAuth2 client the PKCE browser flow exchanges for a token. With both set, the next Gemini session opens an Ory login in your browser; sign in with the same seeded credentials from step 1, and the token is reused on subsequent sessions until it expires. This is what makes `permissions enforce` (see [Agent security](#agent-security)) deny on the right identity later.
57
+ ```bash
58
+ npx -y -p @ory/gemini-cli ory-gemini watch
59
+ ```
82
60
 
83
- That's the full Ory DX path. Stop here if you're just evaluating the extension. Continue to [Agent security](#agent-security) when you're ready to enforce.
61
+ Spans are also written to `~/.config/ory-agent-plugins/gemini-cli/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.
62
+ - **Debug log.** For a verbose play-by-play, set `ORY_AGENT_DEBUG=true`; structured logs land in `~/.config/ory-agent-plugins/gemini-cli/ory-agent-debug.log`.
84
63
 
85
- ## What's included
64
+ ### Ready to enforce?
86
65
 
87
- ### Skills for scaffolding Ory into your application
66
+ When the watch-mode logs look right, turn on blocking with one command (setup already granted you the built-in tools):
88
67
 
89
- The extension bundles a catalog of skills that Gemini auto-invokes by description. Ask Gemini in natural language or invoke a skill directly:
90
-
91
- **Start here — add Ory auth to your app:**
92
-
93
- - **`ory-auth-setup`** — full project setup. Install the Ory CLI, create an Ory Network project (or use the local one), add Ory Elements, configure the SDK, build the auth pages, wire session middleware.
94
- - **`ory-login-flow`** — login, registration, recovery, verification, and settings pages with Ory Elements. Next.js App Router and React SPA variants.
95
- - **`ory-social-login`** — Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
96
- - **`ory-local-dev`** — drive the local Ory stack from within Gemini to prototype and test without a remote project.
97
-
98
- **Going further:**
99
-
100
- - **`ory-permissions-onboarding`** — bootstrap permissions for built-in tools, switch between observe and enforce mode, troubleshoot denials.
101
- - **`ory-build-integration`** — pull the runnable subset of an `ory/integrates` template (webhook / config / http-event) into your own app and wire it to your Ory project — no contribution/registry concerns.
102
- - **`ory-contribute-integration`** — author a brand-new integration as a contribution to `ory/integrates`, including `registry.entry.yaml`, the `Maintained by:` footer, DCO sign-off, and registry regeneration.
103
- - **`ory-e2b-sandbox`** — scaffold an [E2B](https://e2b.dev) sandbox template that boots with this extension preinstalled and registered, so every sandbox session is gated by Ory auth, permissions, and tracing without any per-sandbox setup.
104
- - **`ory-build-agent`** — drop `@ory/argus` directly into a custom agent you own (Claude Agent SDK, OpenAI Agents SDK, Mastra, Vercel AI SDK, PydanticAI, LangGraph, Mistral AI, or Salesforce Agentforce) so the user is authenticated, every tool call is authorized against Ory Permissions, and the lifecycle emits trace spans.
105
- - **`ory-temporal-worker`** — scaffold a [Temporal](https://temporal.io) TypeScript worker per the [official local-dev guide](https://docs.temporal.io/develop/typescript/set-up-your-local-typescript), with every Activity gated by an Ory permission check, the worker's agent identity resolved via DCR, and the full lifecycle emitting trace spans.
106
-
107
- ### Ory MCP server
108
-
109
- Bundled and registered automatically. Exposes the Ory CLI and the Ory Network REST API as MCP tools so Gemini can manage identities, OAuth2 clients, projects, permissions, and configuration without ever leaving the chat. Useful for seeding test data, verifying a scaffolded integration, or running one-off admin tasks.
110
-
111
- ### Local Ory stack
112
-
113
- ```
114
- /ory:local-up # start a local Ory instance in Docker
115
- /ory:local-down # tear it all down
116
- /ory:temporal-up # start a local Temporal dev server (for ory-temporal-worker)
68
+ ```bash
69
+ npx -y -p @ory/gemini-cli ory-gemini permissions enforce
117
70
  ```
118
71
 
119
- `local-up` runs a complete Ory on your laptop: the Ory APIs (Identities, OAuth2, Permissions) at `http://localhost:4000`, a login UI on `:4455` (not :3000, to avoid Next.js port conflicts), and Jaeger (the trace viewer) on `:16686`. A test user identity is seeded and its credentials are printed for you. Use it to:
72
+ Now a denied tool is actually blocked and Gemini 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 — or just ask Gemini in chat, e.g. *"grant me use of the shell tool."*
120
73
 
121
- - **Learn Ory hands-on** without signing up for a hosted project.
122
- - **Prototype** flows (login, social, MFA, recovery, permissions) against a real Ory backend.
123
- - **Test** an auth integration end-to-end before pushing anything to a real environment.
124
- - **Develop** your application against the same identity, OAuth2, and permission surfaces you'll ship with.
74
+ ## Also: add login to your own app
125
75
 
126
- ## Pointing at a real Ory project
76
+ Beyond securing Gemini, the extension helps you build Ory into whatever you're working on. Ask Gemini *"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. Start that local Ory with `/ory:local-up` (it prints a test email + password to sign in with) and tear it down with `/ory:local-down`.
127
77
 
128
- The Quickstart uses the local stack. If you have a hosted [Ory Network](https://console.ory.sh) project (Ory's managed cloud), point the extension at it with a single configure command. **The extension requires `--oauth2-client-id` whenever `--project-url` is provided** — register the client first (see [Register the user OAuth2 client](#register-the-user-oauth2-client) below), then run:
78
+ Bundled **skills** (just ask in plain language) cover more: `ory-auth-setup`, `ory-login-flow`, `ory-social-login` (Google, GitHub, Apple…), `ory-permissions-onboarding`, and playbooks for wiring Ory into your own agents, E2B sandboxes, or Temporal workers. Real `/ory:` **slash commands** run the local stack (`/ory:local-up`, `/ory:local-down`, `/ory:temporal-up`). And a built-in **Ory MCP server** lets Gemini manage identities, projects, and permissions straight from chat.
129
79
 
130
- ```bash
131
- npx -y -p @ory/gemini-cli ory-gemini configure \
132
- --project-url https://<id>.projects.oryapis.com \
133
- --oauth2-client-id <public OAuth2 client id>
134
- ```
80
+ The local stack runs a complete Ory on your laptop: the Ory APIs (Identities, OAuth2, Permissions) at `http://localhost:4000`, a login UI on `:4455` (not `:3000`, to avoid Next.js port conflicts), and Jaeger (the trace viewer) on `:16686`. Everything works offline.
135
81
 
136
- - **`--project-url`** points the extension at your project. The **agent identity** (machine credentials for Gemini's outgoing Ory API calls) is created automatically on first run via OAuth2 Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) against the project's `/oauth2/register` endpoint — no manual step required for that one.
137
- - **`--oauth2-client-id`** is required because the **user** PKCE browser flow (triggered by `ORY_USER_LOGIN=true`) cannot self-register — you must register a public OAuth2 client ahead of time and supply its id here. The configure command refuses to save a project URL without it, so you don't end up with a silently-broken setup later. See [Register the user OAuth2 client](#register-the-user-oauth2-client) below for the exact CLI / Console steps.
138
- - **`--api-key ory_pat_...`** is optional — pass it only if you want to override the auto-registered agent identity with a static personal access token (operator override; rarely needed).
82
+ ## Configure by hand (CI / advanced)
139
83
 
140
- If you only want audit logging (no auth or permission checks), substitute `--audit-only` — the OAuth2 client id is not required in that mode:
84
+ 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 and extensions; environment variables win when both are set.
141
85
 
142
86
  ```bash
143
- npx -y -p @ory/gemini-cli ory-gemini configure --audit-only
87
+ npx -y -p @ory/gemini-cli ory-gemini configure \
88
+ --project-url https://<slug>.projects.oryapis.com \
89
+ --oauth2-client-id <login client id> \
90
+ --user-login
144
91
  ```
145
92
 
146
- The same settings can be supplied via environment variables (`ORY_PROJECT_URL`, `ORY_OAUTH2_CLIENT_ID`, `ORY_AGENT_API_KEY`) — env vars take precedence over the config file when both are set, which is what most CI / scripted setups want.
147
-
148
- Config is saved to `~/.config/ory-agent-plugins/config.json` and shared across every Ory agent plugin or extension on the machine.
149
-
150
- Without configuration the extension still loads cleanly and runs in **pass-through mode**: skills and commands work, but nothing is blocked. You can stay in pass-through mode indefinitely if you only want the DX features.
93
+ Gemini's own identity registers itself automatically on first run — nothing to create. The `--oauth2-client-id` is the one piece browser sign-in needs, so `configure` won't save a project URL without it; the guided setup makes it for you, or see below to do it by hand. For logging-only with no checks, use `--audit-only`. The matching env vars are `ORY_PROJECT_URL`, `ORY_OAUTH2_CLIENT_ID`, `ORY_USER_LOGIN`, and `ORY_AGENT_API_KEY`.
151
94
 
152
- ### Register the user OAuth2 client
153
-
154
- If you plan to turn on `ORY_USER_LOGIN=true` (recommended — it's what attributes every tool call to *you* rather than a fallback `session:<id>` subject), your hosted Ory project needs a **public** OAuth2 client (no client secret) registered ahead of time. The local stack provisions this for you automatically; against a hosted project you have to register it once yourself.
95
+ <details>
96
+ <summary>Create the sign-in client by hand</summary>
155
97
 
156
- The client must list **all four** loopback ports as redirect URIs:
98
+ The guided setup normally does this. To do it yourself, create a **public** OAuth2 client (no secret) listing all four loopback URLs — the extension tries each in turn so sign-in survives a busy port:
157
99
 
158
100
  - `http://127.0.0.1:47823/callback`
159
101
  - `http://127.0.0.1:47824/callback`
160
102
  - `http://127.0.0.1:47825/callback`
161
103
  - `http://127.0.0.1:47826/callback`
162
104
 
163
- The extension walks the four ports at runtime so the login can survive any one of them being occupied — Ory rejects the callback if the port it lands on isn't on the registered list, so register all four.
164
-
165
- Create the client with the [Ory CLI](https://www.ory.com/docs/guides/cli/installation):
105
+ Create it with the [Ory CLI](https://www.ory.com/docs/guides/cli/installation):
166
106
 
167
107
  ```bash
168
108
  ory create oauth2-client --project <project-id> \
@@ -177,103 +117,36 @@ ory create oauth2-client --project <project-id> \
177
117
  --redirect-uri http://127.0.0.1:47826/callback
178
118
  ```
179
119
 
180
- …or in the [Ory Console](https://console.ory.sh) under *OAuth2* → *Clients* → *Create client* (pick "Public client", set "Authorization Code" + "Refresh Token" grants, scopes `openid offline_access`, paste the four redirect URIs above). Then persist the issued id with the configure command (preferred — survives across sessions):
181
-
182
- ```bash
183
- npx -y -p @ory/gemini-cli ory-gemini configure \
184
- --project-url https://<id>.projects.oryapis.com \
185
- --oauth2-client-id <client-id from the step above>
186
- ```
187
-
188
- …or set it in the environment alongside `ORY_USER_LOGIN`:
189
-
190
- ```bash
191
- export ORY_USER_LOGIN=true
192
- export ORY_OAUTH2_CLIENT_ID=<client-id from the step above>
193
- ```
194
-
195
- Headless / CI runs that already hold a session token can skip this entirely by setting `ORY_USER_SESSION_TOKEN` instead — no browser flow runs, so no OAuth2 client is needed.
196
-
197
- ## Agent security
198
-
199
- Once the extension is pointed at an Ory project (local or hosted), Gemini's session and every tool call can be governed by Ory.
200
-
201
- - **Authentication.** Two identities. The human at the keyboard (the **user**) authenticates interactively via Ory Identities when user login is enabled (`ORY_USER_LOGIN=true`, off by default — browser PKCE flow on first session, persisted token thereafter). The Gemini process (the **agent**) gets its own OAuth2 identity, self-registered via [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) on first run.
202
- - **Authorization.** Before any tool runs, the extension checks [Ory Permissions](https://www.ory.com/docs/keto) (Zanzibar-style relations) against the user's subject and blocks the call on `deny`. MCP tool calls additionally get a server-level check.
203
- - **Audit.** Every decision (allow, deny, fallback) is recorded as a structured trace span: NDJSON file output and/or OTLP/HTTP export to Jaeger, Honeycomb, Grafana, and similar collectors. The user → agent delegation is written to Ory as a relation so *"agent X acting on behalf of user Y"* stays queryable after tokens expire.
204
-
205
- The extension is **fail-open** on its own infrastructure failures (network errors, rate limits, missing config), so enforcement is only as strong as your permission grants — grant explicit `use` on the tools each user should be able to run.
120
+ …or make one in the [Ory Console](https://console.ory.sh) under *OAuth2* → *Clients* → *Create client* (pick "Public client", "Authorization Code" + "Refresh Token" grants, scopes `openid offline_access`, paste the four URLs). Pass the resulting id to `configure --oauth2-client-id`. Running headless with a session token already? Set `ORY_USER_SESSION_TOKEN` and skip the browser step entirely.
206
121
 
207
- ### Enable enforcement
208
-
209
- After install the extension runs in **observe mode**: every tool call is checked against Ory Permissions, but a deny is recorded as a `permission.observe_deny` audit span and the tool runs anyway. This lets you see what *would* be blocked before turning on hard blocking.
210
-
211
- 1. **Turn on user login.** It's off by default. In your shell:
212
-
213
- ```bash
214
- export ORY_USER_LOGIN=true
215
- export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>
216
- ```
217
-
218
- The next Gemini session opens a browser for PKCE login. Subsequent sessions reuse the persisted token until it expires.
219
-
220
- `ORY_OAUTH2_CLIENT_ID` is required when `ORY_USER_LOGIN` is on: PKCE needs a public OAuth2 client registered with the four loopback redirect URIs (`http://127.0.0.1:47823..47826/callback`) to exchange the authorization code for a token. The local stack provisions one and prints the export in its `local up` banner; for a hosted Ory project see [Register the user OAuth2 client](#register-the-user-oauth2-client) for the exact CLI / Console steps. Headless / CI runs can skip the browser flow entirely by pre-supplying `ORY_USER_SESSION_TOKEN` instead.
221
-
222
- 2. **Bootstrap permissions for the built-in tools.** One idempotent command grants the current user `use` on every tool Gemini ships with (read_file, write_file, shell, …):
223
-
224
- ```bash
225
- npx -y -p @ory/gemini-cli ory-gemini permissions bootstrap
226
- ```
227
-
228
- If a user identity is already cached at install time, the installer runs this for you automatically — re-run after adding tools, switching subjects, or changing the namespace.
229
-
230
- 3. **Check coverage.** `permissions status` probes every tool in the harness's catalog and prints allowed / denied per tool:
231
-
232
- ```bash
233
- npx -y -p @ory/gemini-cli ory-gemini permissions status
234
- ```
235
-
236
- Add permissions for any MCP server tools or custom commands by hand, or via the Ory MCP server from inside Gemini (*"grant me use on the shell tool"*).
237
-
238
- 4. **Promote to enforce.** Once the observe-mode logs look right, switch over:
239
-
240
- ```bash
241
- npx -y -p @ory/gemini-cli ory-gemini permissions enforce
242
- ```
122
+ </details>
243
123
 
244
- Denies now block the tool call; Gemini shows the denial reason and the decision is recorded as a `tool.block` trace span with `blocked: true`. Switch back any time with `permissions observe`.
124
+ With nothing configured, the extension still loads and runs in **pass-through mode**: skills, slash commands, and logging work, but no checks run and nothing is blocked. Perfectly fine if you only want the app-building features.
245
125
 
246
- ## CLI reference
126
+ ## Commands
247
127
 
248
128
  ```
249
- npx -y -p @ory/gemini-cli ory-gemini install [--link]
250
- npx -y -p @ory/gemini-cli ory-gemini uninstall
251
- npx -y -p @ory/gemini-cli ory-gemini configure [--project-url <url> --oauth2-client-id <id>] [--api-key <key>] [--audit-only]
252
- npx -y -p @ory/gemini-cli ory-gemini agent <status|unregister> Manage the agent's OAuth2 identity
253
- npx -y -p @ory/gemini-cli ory-gemini permissions <status|bootstrap|observe|enforce>
254
- npx -y -p @ory/gemini-cli ory-gemini local <up|down|status|seed|logs|env|configure|reset>
255
- npx -y -p @ory/gemini-cli ory-gemini status
129
+ ory-gemini install | uninstall Install/remove; --reconfigure re-runs setup, --no-configure skips it
130
+ ory-gemini status Show configuration, identities, permission coverage, recent activity
131
+ ory-gemini watch Tail the live trace stream (OTel spans)
132
+ ory-gemini permissions <cmd> status | bootstrap | observe (watch) | enforce (block)
133
+ ory-gemini configure <flags> Point at a project by hand (--project-url, --oauth2-client-id, --user-login, --audit-only)
134
+ ory-gemini agent <status|unregister> Manage Gemini's own auto-created identity
135
+ ory-gemini local <up|down|status|…> Run / manage a local Ory in Docker
256
136
  ```
257
137
 
258
- Highlights:
259
-
260
- - `agent status` — show the current persisted DCR identity for the agent.
261
- - `permissions observe` / `permissions enforce` — switch between "log denies, allow through" (the install default) and "block denies." `permissions bootstrap` writes `use` permissions for the harness's built-in tools so the promotion path doesn't require hand-writing relations.
262
- - `configure --audit-only` — kill switch that disables Ory entirely (no auth, no permission checks; only audit logging of tool invocations). For phased rollouts, prefer `permissions observe` over `--audit-only`.
263
- - `local seed` / `local env` — reseed the test user, or print env vars for pointing other tools at the local stack.
138
+ All prefixed with `npx -y -p @ory/gemini-cli`.
264
139
 
265
140
  ## Troubleshooting
266
141
 
267
- - **`/ory:local-up` fails.** Make sure Docker is running and ports `4455` (login UI), `4000`, `4100`, and `16686` are free.
268
- - **PKCE login loops.** Clear persisted state with `npx -y -p @ory/gemini-cli ory-gemini agent unregister` and retry.
269
- - **`npx` fetches an old version.** Force a fresh fetch: `npx -y -p @ory/gemini-cli@latest ory-gemini …`.
270
- - **Need more signal.** Set `ORY_AGENT_DEBUG=true` and `ORY_AGENT_LOG_FILE=/tmp/ory.log` to capture structured logs.
142
+ - **`/ory:local-up` fails** — make sure Docker is running and ports `4000`, `4100`, `4455`, and `16686` are free.
143
+ - **Browser sign-in loops** — reset with `ory-gemini agent unregister` and try again.
144
+ - **`npx` grabbed an old version** — force the latest: `npx -y -p @ory/gemini-cli@latest ory-gemini …`.
145
+ - **Want to see what's happening** — `npx -y -p @ory/gemini-cli ory-gemini status` for a snapshot, `npx -y -p @ory/gemini-cli ory-gemini 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/gemini-cli/` (see [See what's happening](#see-whats-happening)).
271
146
 
272
- ## Links
147
+ ## Learn more
273
148
 
274
- - [Ory documentation](https://www.ory.com/docs/)
275
- - [Ory Network console](https://console.ory.sh)
276
- - [Ory Elements](https://github.com/ory/elements)
149
+ - [Ory documentation](https://www.ory.com/docs/) · [Ory Console](https://console.ory.sh) · [Ory Elements](https://github.com/ory/elements)
277
150
  - [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli)
278
151
 
279
152
  ## License
package/dist/cli/main.js CHANGED
@@ -61,14 +61,19 @@ function main() {
61
61
  const [command, ...args] = process.argv.slice(2);
62
62
  switch (command) {
63
63
  case "install":
64
+ (0, argus_1.beginDeferNextSteps)();
64
65
  install(args);
65
- postInstallPermissions("ory-gemini", "gemini-cli").then(() => process.exit(0), (err) => {
66
+ (0, argus_1.runPostInstall)("ory-gemini", "gemini-cli", args).then(() => process.exit(0), (err) => {
66
67
  console.error(err.message ?? err);
67
68
  process.exit(1);
68
69
  });
69
70
  break;
70
71
  case "uninstall":
71
72
  uninstall(args);
73
+ (0, argus_1.clearCredentialsForUninstall)().then(() => process.exit(0), (err) => {
74
+ console.error(err.message ?? err);
75
+ process.exit(1);
76
+ });
72
77
  break;
73
78
  case "configure":
74
79
  (0, argus_1.runConfigureCommand)("ory-gemini", args);
@@ -100,6 +105,9 @@ function main() {
100
105
  process.exit(1);
101
106
  });
102
107
  break;
108
+ case "watch":
109
+ (0, argus_1.runWatchCommand)("gemini-cli", args);
110
+ break;
103
111
  case "help":
104
112
  case "--help":
105
113
  case "-h":
@@ -181,12 +189,6 @@ function manualSetup(args) {
181
189
  process.argv = ["node", "setup.js", ...args];
182
190
  require("./setup.js");
183
191
  }
184
- async function postInstallPermissions(binName, harness) {
185
- const bootstrapped = await (0, argus_1.maybeAutoBootstrap)(binName, harness);
186
- (0, argus_1.printPermissionsOnboardingHelp)(binName, harness, {
187
- bootstrappedAutomatically: bootstrapped,
188
- });
189
- }
190
192
  /**
191
193
  * Print a three-line quickstart so a fresh user sees the happy path
192
194
  * before the more detailed credentials and permissions banners scroll
@@ -217,7 +219,7 @@ function help() {
217
219
  ory-gemini — Ory plugin for Gemini CLI
218
220
 
219
221
  Usage:
220
- npx ory-gemini <command> [options]
222
+ npx -y -p @ory/gemini-cli ory-gemini <command> [options]
221
223
 
222
224
  Commands:
223
225
  install [--link] Install the Ory extension into Gemini CLI
@@ -227,6 +229,7 @@ Commands:
227
229
  permissions <cmd> Manage permission mode and tool permissions (status, bootstrap, observe, enforce)
228
230
  setup [--project-dir] Write hooks directly to settings.json (fallback)
229
231
  status Show plugin status and configuration
232
+ watch [trace-file] Tail the trace stream (OTel spans) live
230
233
  local <cmd> Manage local Ory dev environment (up, down, status, seed, ...)
231
234
 
232
235
  After installing, the extension hooks into these Gemini CLI lifecycle events:
@@ -235,10 +238,10 @@ After installing, the extension hooks into these Gemini CLI lifecycle events:
235
238
  AfterTool Audit log tool executions
236
239
 
237
240
  Examples:
238
- npx ory-gemini install # Install extension
239
- npx ory-gemini install --link # Link for development
240
- npx ory-gemini status # Check configuration
241
- npx ory-gemini uninstall # Remove extension
241
+ npx -y -p @ory/gemini-cli ory-gemini install # Install extension
242
+ npx -y -p @ory/gemini-cli ory-gemini install --link # Link for development
243
+ npx -y -p @ory/gemini-cli ory-gemini status # Check configuration
244
+ npx -y -p @ory/gemini-cli ory-gemini uninstall # Remove extension
242
245
  `);
243
246
  }
244
247
  main();
package/dist/cli/setup.js CHANGED
@@ -97,6 +97,18 @@ function main() {
97
97
  (0, assets_js_1.installGeminiOryAssets)(geminiDir);
98
98
  console.log(`Ory hooks and MCP server installed to ${settingsPath}`);
99
99
  console.log(`Ory skills and commands installed to ${geminiDir}`);
100
- (0, argus_1.printNextSteps)("Gemini CLI", "npx ory-gemini-setup --uninstall");
100
+ (0, argus_1.printNextSteps)("Gemini CLI", "npx -y -p @ory/gemini-cli ory-gemini-setup --uninstall", {
101
+ binName: "ory-gemini",
102
+ harness: "gemini-cli",
103
+ });
101
104
  }
102
105
  main();
106
+ // When invoked directly as the `-setup` bin with `--uninstall`, also clear
107
+ // stored Ory credentials. When required by the plugin's main CLI, that
108
+ // command owns the purge, so the `require.main` guard prevents a double run.
109
+ if (require.main === module && process.argv.includes("--uninstall")) {
110
+ (0, argus_1.clearCredentialsForUninstall)().then(() => process.exit(0), (err) => {
111
+ console.error(err.message ?? err);
112
+ process.exit(1);
113
+ });
114
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ory/gemini-cli",
3
- "version": "0.11.0",
3
+ "version": "0.12.0",
4
4
  "description": "Ory extension for Gemini CLI: scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://ory.com",
@@ -68,7 +68,7 @@
68
68
  "gemini-extension"
69
69
  ],
70
70
  "dependencies": {
71
- "@ory/argus": "0.11.0"
71
+ "@ory/argus": "0.12.0"
72
72
  },
73
73
  "engines": {
74
74
  "node": ">=22"