Gephyr CLI

Set up and change your apps from a terminal, or let an AI coding agent like Claude Code or Cursor do it.

npx gephyr login

It needs Node 18 or later and nothing else. Every command can answer in JSON (--json) for scripts and agents, and gephyr mcp gives AI coding agents the same commands as tools. Sign-in setup (OAuth, Supabase, Firebase and the others) stays in the console.

Signing in

Run npx gephyr login. It shows a code like BCDF-GHJK and opens gephyr.ai/app/cli.
Sign in to the console if you aren’t already, and type the code.
Check the computer’s name and where the login started. Gephyr warns you if it started in another country than you’re in now, through Tor, or somewhere it can’t place.
Click Approve. The terminal is signed in as you.

Codes work for 10 minutes and once only. Only type a code from a terminal in front of you: never one someone sent you, even if they say they’re from Gephyr. When it’s done, the terminal says which email approved it.

An agent’s shell only shows output when a command ends, so it signs in in two steps:

gephyr login --start    # prints the code: the agent shows it to you
gephyr login --finish   # waits up to 100 seconds for you to approve (--wait to change)

You still type the code and approve it yourself. If --finish stops before you’ve approved, it ends with exit code 2 and the agent runs it again.

Let your AI agent set up your app

If you work in Claude Code, Cursor, Codex or another coding agent, it can set your app up for you from your codebase. Paste this into it (the console’s Gephyr CLI page has a copy button):

Set up our app on Gephyr (gephyr.ai), so AI agents like ChatGPT and Claude can use it for our users. Use the Gephyr CLI: run `npx -y gephyr --help` to see the commands.

1. Sign in: run `npx -y gephyr login --start` and show me the link and code. Then run `npx -y gephyr login --finish` while I approve it (again if it says it's still waiting). Never approve it yourself.
2. Find our API docs in this codebase: an OpenAPI, Swagger or Postman file in JSON or YAML. If there isn't one, write an OpenAPI 3 JSON file from our API routes and show it to me first.
3. Create the app with `npx -y gephyr create "<our app name>"` and import the docs with `npx -y gephyr import`.
4. Go through `npx -y gephyr actions <app>` with me. Suggest a level for each action: read for look-ups, write for everyday changes, confirm for payments, cancellations and deletions, and off for anything agents shouldn't do (admin, internal, bulk). Change levels only once I agree.
5. Tell me what's left in the Gephyr console (how our users sign in), and publish only when I say so.

It signs in with a code you approve in the console, imports your API docs (or writes them from your code first, and shows you), and checks with you before changing access levels or publishing. Setting up how your users sign in stays in the console.

Commands

gephyr create "FitApp"
gephyr import fitapp ./openapi.json
gephyr actions set fitapp cancel_booking confirm
gephyr publish fitapp

Command	What it does
`apps`	Your apps, with their status and MCP address
`create <name> [--slug <link>]`	Create an app. The link becomes its address, `mcp.gephyr.ai/t/<link>`
`status <app>`	Status, API address, whether sign-in is set up, actions, its other links, changes not yet published, the safety check, and what no longer matches your API docs
`import <app> <file or link> [--base-url <url>] [--replace]`	Import OpenAPI, Swagger or Postman docs (a `.json`, `.yaml` or `.yml` file up to 2 MB, or a link). Gephyr designs the actions and suggests a level for each. An app that already has actions keeps them unless you add `--replace`. If the docs name a different API address from the app’s, nothing is saved until you choose one with `--base-url`. Imported from a link, Gephyr checks it daily
`import <app> [file or link] --check`	Check the actions against API docs and say what a change breaks, changing nothing. With a file or link, nothing is saved (use it in your build); with neither, Gephyr reads the docs link it checks daily. Exit code `1` when something may fail
`actions <app>`	Actions and their access levels
`actions set <app> <action> <level>`	`read`, `write`, `confirm` or `off` (see Tools and access)
`publish <app>`	Publish, so your users’ AI apps get your changes. If something’s missing, it says what, and it lists safety warnings
`pause <app>`	Take a live app offline until you publish again
`stats <app> [--days 1, 7 or 30] [--link <link id> or main]`	What your app’s Overview shows: calls and outcomes against the period before, people and the setup page, what went wrong and how to fix it, a failing action, answers cut to fit, approved actions to check, and Ask first. By action, AI app and country, and what users asked for, on Growth and up. `--json` adds the chart and busiest times. `--link` shows one of your other links, or `main` for the app’s own address
`activity <app> [--failed] [--days 1, 7 or 30]`	The latest calls from the Activity tab, or with `--failed` only failed and stopped ones (Launch and up)
`receipts <app> [--id <receipt>] [--ref <your id>] [--before <time>]`	Receipts of approved Ask first actions, newest first: by receipt number, by the id your API answered with (a booking or payment id), or the latest. `--json` includes the signed receipt to send on
`suggestions <app>`	What to fix next from your Overview (Gephyr suggests). It changes nothing: make the change in the console
`people <app> [--days 1, 7 or 30]`	The most active signed-in people, by anonymous ID, with how many of their calls limits stopped, their last call, and whether they’re connected or blocked now (Protection → Disconnect people)
`find <app> <user-id>`	A person’s anonymous ID from their user ID in your app (the ID your sign-in uses), and whether they’re connected or blocked. Nothing is stored
`blocked <app>`	The people blocked from your app. Disconnecting, blocking and unblocking are in the console only
`whoami`	Who this computer is signed in as, and your workspaces
`logout`	Sign this computer out

<app> is the app’s link (like fitapp) or its id. Add --json to any command for JSON, errors included. Exit codes: 0 done, 1 error (or, with --check, something may fail), 2 still waiting for approval.

For AI coding agents (MCP)

gephyr mcp runs the CLI as an MCP server, so your agent gets the commands as tools. In Claude Code:

claude mcp add gephyr -- npx -y gephyr mcp

In Cursor and other clients, add a stdio server with the command npx and arguments -y gephyr mcp.

To sign in, the agent calls gephyr_login, shows you the code, and finishes once you’ve approved. Publishing, pausing and changing levels are marked as changes, and the agent is told to check with you first.

What a signed-in computer can do

It acts as you, on the apps in your workspaces, for what the CLI needs:

Can: list and read your apps and what their dashboards show (stats, recent calls, receipts, what to fix next, the most active people and who’s blocked, and find someone by their user ID), create an app, import an OpenAPI file and check actions against one, choose each action’s access level, publish and pause.
Console only: sign-in setup, billing, deleting an app, disconnecting, blocking and unblocking people, the message board, Gephyr AI and Test with AI (they use your monthly allowances), approving or signing out computers. Once an app has been published, its API address, who can use it and its protection limits also change only in the console, so a lost laptop can’t send your users’ calls anywhere else. A signed-in computer also can’t make a live app’s actions less careful. Each action has to be at least as careful as the live action with its name or its endpoint, so renaming an action or pointing it at another endpoint doesn’t get round that. A new endpoint can only be added on Ask first, except a plain lookup (a GET whose name, path, query, headers and inputs don’t say it cancels, pays, deletes or changes anything, and whose path names what it looks up, like /people/{id}), which can come in on Read. A lookup where the agent picks part of the route, like /{section}/{id}, comes in on Ask first. An endpoint that’s Off in the live app stays Ask first, and so does any path that could reach it, and a live Ask first action can’t change what it sends, or the words its approval shows: its description and the names of its inputs, or add an input (any action saved on its endpoint keeps them too). A live action whose inputs now take other values (a choice added or removed) is held to every live action on its endpoint, and a live lookup changed so the agent picks part of the route, or so it says it cancels, deletes or changes something, needs Ask first like a new one. Nor can it make a live action show agents more: fields you hide stay hidden, text marked as written by other people stays marked, and it can’t add fields the live action leaves out (hiding more is fine), or change a live action’s price check or the id on its receipts. Make those changes in the console.
Never: Gephyr staff access.

Each published version records whether a signed-in computer published it.

Signed-in computers

The Gephyr CLI page lists each computer signed in as you, with when it signed in and was last used. Sign out stops it at once; gephyr logout does the same from the terminal (if it can’t reach Gephyr, it keeps the sign-in and says so, so you can try again). A computer is also signed out after 90 days without use, and a year after it signed in. Up to 20 at a time.

Signing out of the console or changing your password doesn’t sign out your computers. If a laptop is lost or someone may have your sign-in, sign its computer out here.

The CLI keeps its sign-in in a file only your user account can read. Gephyr stores a fingerprint of it and its first few characters, never the sign-in itself.

Something missing or wrong? Email hello@gephyr.ai.