Skip to main content

UI Testing CLI reference: keploy login and keploy mcp-install​

View as Markdown
FreeTeamsScaleEnterpriseSelf-HostedDedicated

The keploy binary has no UI Testing commands of its own. For UI Testing it does two things: it signs you in to Keploy, from a terminal or from an AI agent's shell, and it connects your AI agent to the Keploy MCP server, whose tools then set up capture and read flows and journeys. This page covers the released keploy binary.

To install it, see Install Keploy.

Sign in from a terminal or an agent​

keploy login

keploy login signs you in through your browser and waits until you approve the sign-in. With an API key in KEPLOY_API_KEY, or a session it saved before, it uses that instead.

An AI agent's shell shows a command's output only when the command exits, so an agent signs in in two steps:

keploy login --no-wait --json
# a person opens the link and approves the code
keploy login --finish --json
  1. keploy login --no-wait prints the sign-in link and code and exits without waiting. The agent shows them to you.
  2. You open the link and approve the code.
  3. keploy login --finish collects the session. It waits up to 70 seconds for the approval, and can be run again until the code expires.
FlagWhat it does
--no-waitPrint the sign-in link and code and exit instead of waiting.
--finishCollect the session for the sign-in started by --no-wait.
--newWith --no-wait: discard the sign-in waiting here and start a new one. Without it, --no-wait shows the waiting code or link again.
--jsonWith --no-wait or --finish: print the answer as one JSON document on stdout, for AI agents and tools. Logs go to stderr.
--api-keyA Keploy API key for this invocation, in place of the KEPLOY_API_KEY environment variable.
--showPrint the API key a login uses here (its last 4 characters only) and where it comes from, then exit without signing in.
--manual-loginAsk for an API key to paste instead of opening the browser.

When an API key is set, in KEPLOY_API_KEY or with --api-key, and the server accepts it, keploy login --no-wait answers that you are signed in and starts no sign-in.

Connect your agent​

keploy mcp-install --editor claude-code

keploy mcp-install uses the session keploy login saved: sign in first. It mints a personal access token for the Keploy MCP server and writes the server, https://api.keploy.io/client/v1/mcp with that token, into your agent's MCP configuration as keploy. The UI capture tools are then available to the agent: see MCP tools.

FlagWhat it does
--editor <name>The agent to configure: claude-code, cursor, windsurf, claude-desktop, codex, antigravity or github-copilot. For github-copilot, which has no configuration file on disk, it prints a block to paste. Pass this or --all.
--allConfigure every MCP-aware agent found on this machine. GitHub Copilot is not detected: configure it with --editor github-copilot.
--scope <scope>global (the default) configures the agent for every project on this machine. project configures it for the current directory, for Claude Code, Cursor and Codex; for Cursor and Codex that writes the token into a file in your repo.
--api-server-urlThe Keploy API server to connect to. The default is https://api.keploy.io. Pass your own server's URL when you self-host.
--rotateMint a new token and revoke the current one. Every agent configured with the old token must then be configured again.
--show-tokenPrint the real token inside the copy-paste blocks. Off by default, because those blocks end up in terminal scrollback and CI logs.

The token is minted once and reused: mcp-install keeps it in ~/.keploy/mcp.yaml, so configuring one more agent leaves the others working. It expires after 90 days. When your agents start getting 401, run keploy mcp-install --rotate: without --rotate, mcp-install hands out the cached token again. Minting a new one, with --rotate, on another machine or by signing in to the Keploy VS Code extension, which mints its token the same way, revokes the ones minted before, and agents still holding them lose access.

The token carries the scopes your role in the company allows. Effective access is still what your role holds on each app: setting up capture needs testgen:run on the app, and reading flows needs app:view.

In CI​

No person can approve a sign-in code in CI. To sign the keploy binary in there, set KEPLOY_API_KEY to a Keploy API key.

The UI capture steps a CI job takes, such as checking capture status or reading the journey plan, are calls to the REST API with an API key, not keploy commands.

keploy ui​

The keploy ui commands, the runner keploy ui run that replays journeys as Playwright tests among them, are not in a release build yet. In the released binary, keploy ui --help answers Error: unknown command "ui" for "keploy". Replaying journeys as Playwright tests is in beta: see what works today.