Package Exports

@ory/gemini-cli

Readme

Ory Agent Extension: Gemini CLI

Ory bundled into 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.

You don't need an Ory account or any prior Ory experience to start.

Prerequisites

Gemini CLI installed and signed in
Node.js ≥ 24
Docker (only needed for the local Ory stack)
macOS or Linux. Windows works via WSL2.

Install

In your shell:

gemini extensions install ory-agent-extension

That's it — skills, TOML slash commands, hooks, and the Ory MCP server are now registered.

Alternative install paths

If the public extension registry isn't available, either of these registers the same extension:

# Ory-hosted extension source
gemini extensions install https://github.com/ory/gemini-cli-extension

# Direct installer, no prior npm install required
npx @ory/gemini-cli install
npx @ory/gemini-cli uninstall

If the gemini binary isn't on your PATH, npx -y -p @ory/gemini-cli ory-gemini-setup writes the extension config directly.

Quickstart (≈ 3 minutes)

From any project where you'd like Ory authentication, inside Gemini CLI:

Start a local Ory instance. Ask Gemini "start the local Ory stack" or run:
```
/ory:local-up
```
A banner prints the seeded test user's email and password. Note them — you'll log in with them in step 3.
Scaffold Ory into your project. Ask Gemini "add Ory auth to this app" or invoke the ory-auth-setup skill.

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.
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.

That's the full Ory DX path. Stop here if you're just evaluating the extension. Continue to Agent security when you're ready to enforce.

What's included

Skills for scaffolding Ory into your application

The extension bundles four skills that Gemini auto-invokes by description. Ask Gemini in natural language or invoke a skill directly:

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.
ory-login-flow — login, registration, recovery, verification, and settings pages with Ory Elements. Next.js App Router and React SPA variants.
ory-social-login — Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
ory-local-dev — drive the local Ory stack from within Gemini to prototype and test without a remote project.

Ory MCP server

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, permission tuples, and configuration without ever leaving the chat. Useful for seeding test data, verifying a scaffolded integration, or running one-off admin tasks.

Local Ory stack

/ory:local-up      # start a local Ory instance in Docker
/ory:local-down    # tear it all down

local-up brings up Ory Identities, OAuth2, and Permissions, plus a login UI on :3000 and Jaeger on :16686, all reachable through http://localhost:4000. A test user identity is seeded and the credentials are printed for you. Use it to:

Learn Ory hands-on without signing up for a hosted project.
Prototype flows (login, social, MFA, recovery, permission tuples) against a real Ory backend.
Test an auth integration end-to-end before pushing anything to a real environment.
Develop your application against the same identity, OAuth2, and permission surfaces you'll ship with.

Pointing at a real Ory project

The Quickstart uses the local stack. If you have a hosted Ory Network project, point the extension at it:

npx -y -p @ory/gemini-cli ory-gemini configure \
  --project-url https://<id>.projects.oryapis.com \
  --api-key ory_pat_...

Config is saved to ~/.config/ory-agent-plugins/config.json and shared across every Ory agent plugin or extension on the machine.

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.

Agent security

Once the extension is pointed at an Ory project (local or hosted), Gemini's session and every tool call can be governed by Ory.

Authentication. Two identities. The human at the keyboard (the user) authenticates interactively via Ory Identities when ORY_AUTH_GATE=1 is set. The Gemini process (the agent) gets its own OAuth2 identity, self-registered via Dynamic Client Registration (RFC 7591) on first run.
Authorization. Before any tool runs, the extension checks Ory Permissions (Zanzibar-style relation tuples) against the user's subject and blocks the call on deny. MCP tool calls additionally get a server-level check.
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 tuple so "agent X acting on behalf of user Y" stays queryable after tokens expire.

The extension is fail-open on its own infrastructure failures (network errors, rate limits, missing config), so enforcement is only as strong as your tuples — grant explicit invoke relations for the tools each user should be able to run.

Enable enforcement

Turn on the user gate. In your shell:
```
export ORY_AUTH_GATE=1
```
The next Gemini session opens a browser for PKCE login. Subsequent sessions reuse the persisted token until it expires.
Grant yourself permission to use a tool. Use the Ory MCP server from inside Gemini ("grant me invoke on the Bash tool") or the CLI directly:
```
ory create relationship \
  --namespace AgentTools \
  --object Bash \
  --relation invoke \
  --subject-id <your-user-subject-id>
```
Your subject id is printed at the start of every Gemini session when ORY_AGENT_DEBUG=true.
See a denial. Pick a tool you didn't grant (or remove the tuple) and ask Gemini to use it. The hook blocks the call and Gemini shows the denial reason. The decision is recorded as a tool.block trace span.

CLI reference

npx -y -p @ory/gemini-cli ory-gemini install                             [--link]
npx -y -p @ory/gemini-cli ory-gemini uninstall
npx -y -p @ory/gemini-cli ory-gemini configure                           [--project-url <url>] [--api-key <key>] [--audit-only]
npx -y -p @ory/gemini-cli ory-gemini agent <status|unregister>           Manage the agent's OAuth2 identity
npx -y -p @ory/gemini-cli ory-gemini local <up|down|status|seed|logs|env|configure|reset>
npx -y -p @ory/gemini-cli ory-gemini status

Highlights:

agent status — show the current persisted DCR identity for the agent.
configure --audit-only — record decisions without blocking; useful for a phased rollout.
local seed / local env — reseed the test user, or print env vars for pointing other tools at the local stack.

Troubleshooting

/ory:local-up fails. Make sure Docker is running and ports 3000, 4000, 4100, and 16686 are free.
PKCE login loops. Clear persisted state with npx -y -p @ory/gemini-cli ory-gemini agent unregister and retry.
npx fetches an old version. Force a fresh fetch: npx -y -p @ory/gemini-cli@latest ory-gemini ….
Need more signal. Set ORY_AGENT_DEBUG=true and ORY_AGENT_LOG_FILE=/tmp/ory.log to capture structured logs.

License

Apache-2.0

JSPM

@ory/gemini-cli