Authentication

revyl auth login authorizes the CLI by asking you to approve it in a browser. The browser does not have to be on the same machine, so the same command works on your laptop, inside a cloud agent, over SSH, and in a container. For CI and other unattended machines, set REVYL_API_KEY instead.

Set up with an agent

Paste one prompt and your coding agent does the rest.

Copy setup promptPreview prompt

Setup prompt

Copy

Sign the Revyl CLI in on this machine.

Read https://docs.revyl.com/authentication.md and follow it. It's the current Revyl guide for this, so prefer it over anything you remember about Revyl.

Run `revyl auth login` in the background or a second terminal and give me the approval link it prints while it waits; I'll approve it in my browser within 10 minutes. Don't create an API key for this machine. API keys are for CI, and I'll add `REVYL_API_KEY` to the CI secret store myself.

You're done when `revyl auth status` shows the CLI is signed in.

Ask me before anything that needs my login or approval.

Log InCopy Anchor Link

revyl auth login

The CLI prints an approval URL and a short code, and opens the URL for you when this machine has a browser:

Open this URL to approve, then confirm the code below:

  https://app.revyl.ai/cli/device?code=HTKD-4W2N
  Code: HTKD-4W2N

Waiting for approval (press Ctrl+C to cancel)...

Open the URL wherever you are signed in to Revyl, check that the code on the page matches the one printed here, and approve. The CLI then receives a key scoped to the account you approved with and saves it:

✓ Successfully authenticated as user@example.com
Organization: <org-id>
Credentials saved to ~/.revyl/credentials.json

The code exists so you can confirm you are approving this request. You never type it in — it is already embedded in the URL.

Requests expire after a few minutes. If yours expires before you approve it, run the command again.

Log In Without a BrowserCopy Anchor Link

Use an API key when nobody is present to approve, such as on a build machine.

Getting an API KeyCopy Anchor Link

1. In the Revyl dashboard, go to Settings → API Keys
2. Click Create key, name it (e.g. local-dev, github-actions), and pick an expiration
3. Click Create and copy the key — it is only shown once

Using the KeyCopy Anchor Link

revyl auth login --api-key

You are prompted for the key, and it is validated and stored like any other credential. When scripting, pass it inline as revyl auth login --api-key=rvl_xxx — the = is required, because a space-separated value is ignored and the CLI prompts instead.

Legacy Browser LoginCopy Anchor Link

revyl auth login --browser uses the previous flow, which opens a browser on this machine and listens on a local port. It is kept as an escape hatch for one release and will be removed. Prefer the default.

Check Authentication StatusCopy Anchor Link

revyl auth status

✓ Authenticated
Email: user@example.com
User ID: usr_abc123
Organization: My Company (<org-id>)
Auth Method: browser (persistent key)
Token expires: never
API Key: rvl_xxxx...xxxx

LogoutCopy Anchor Link

revyl auth logout

Environment Variable (CI/CD)Copy Anchor Link

For CI/CD pipelines, set REVYL_API_KEY instead of logging in:

export REVYL_API_KEY=rvl_your_api_key_here

By default the environment variable takes precedence over stored credentials.

Overriding with an Interactive LoginCopy Anchor Link

If REVYL_API_KEY is set in your shell but you need a different account locally, run revyl auth login. The approved credential becomes the active one for all subsequent interactive CLI commands, even while the env var remains set.

This override persists across commands (revyl dev, revyl build, etc.) until you explicitly log out or log in with a different method. CI and non-interactive environments that only set REVYL_API_KEY are unaffected.

GitHub Actions ExampleCopy Anchor Link

- name: Run Revyl Tests
  env:
    REVYL_API_KEY: ${{ secrets.REVYL_API_KEY }}
  run: |
    revyl workflow run smoke-tests

GitLab CI ExampleCopy Anchor Link

test:
  script:
    - revyl workflow run smoke-tests
  variables:
    REVYL_API_KEY: $REVYL_API_KEY

Hosted AgentsCopy Anchor Link

Hosted coding agents (Cursor Cloud and similar) inject REVYL_API_KEY into the agent's shell, but the MCP server runs as a separate process that may not inherit it. The Revyl Cursor plugin bridges the key automatically when a session starts. To do it by hand:

revyl auth persist-cloud-env

This copies REVYL_API_KEY from the current shell into ~/.revyl, where the MCP server reads it on its next tool call. No restart is required. It reads an existing secret and cannot create one — if no key is present, add REVYL_API_KEY as a Runtime Secret and start a fresh agent, or run revyl auth login and approve from your own browser.

See MCP Setup for the full agent configuration.

Credential StorageCopy Anchor Link

Every login method stores credentials in:

~/.revyl/credentials.json

This file contains your API key and is automatically excluded from version control by the CLI's .gitignore template.

TroubleshootingCopy Anchor Link

The Approval Request ExpiredCopy Anchor Link

Requests are short-lived. Run revyl auth login again to start a new one.

"The request was denied"Copy Anchor Link

Someone pressed Deny on the approval page, or you approved a different request. Run revyl auth login again and check the code on the page matches the one the CLI printed.

The Browser Did Not OpenCopy Anchor Link

Expected on a headless machine — the login still works. Copy the printed URL into any browser where you are signed in to Revyl. For a machine with nobody watching, use revyl auth login --api-key instead.

"Invalid API key" ErrorCopy Anchor Link

• Verify the key hasn't expired in the Revyl dashboard
• Check for extra whitespace when copying the key
• Ensure you're using the correct organization's key

"Network error" During LoginCopy Anchor Link

• Check your internet connection
• Verify backend.revyl.ai and app.revyl.ai are reachable from your network
• Try revyl ping to test connectivity

Credentials Not PersistingCopy Anchor Link

• Check write permissions for ~/.revyl/
• Ensure the directory exists: mkdir -p ~/.revyl

"Org mismatch" After Switching AccountsCopy Anchor Link

If you see an org mismatch error after revyl init or revyl dev:

1. Run revyl auth login and approve with the correct account
2. That credential overrides REVYL_API_KEY for local commands
3. Re-run revyl init --force to rebind the project to the new account