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.

Log In

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:

✓ Authenticated as [email protected]
✓ Organization: My Company
✓ 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.

Because approval happens through Revyl rather than a local port, you can run revyl auth login on a headless box and approve it from your phone or laptop. Copy the printed URL over.

Log In Without a Browser

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

Getting an API Key

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

API keys are only shown once. Store it securely.

Using the Key

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

revyl auth status

✓ Authenticated
  Email: [email protected]
  User ID: usr_abc123
  Org ID: org_xyz789
  API Key: rvl_xxxx...xxxx (masked)

Logout

revyl auth logout

Environment Variable (CI/CD)

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

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

GitLab CI Example

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

Hosted Agents

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 Storage

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.

Never commit API keys to version control. Use environment variables or secrets management for CI/CD.

Troubleshooting

The Approval Request Expired

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

”The request was denied”

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 Open

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” Error

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

Check your internet connection
Verify api.revyl.ai is accessible from your network
Try revyl ping to test connectivity

Credentials Not Persisting

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

”Org mismatch” After Switching Accounts

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

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

Getting Started

CLI

Builds

Tests

Develop

Atlas

Integrations

Appendix

Log In

Log In Without a Browser

Getting an API Key

Using the Key

Check Authentication Status

Logout

Environment Variable (CI/CD)

GitHub Actions Example

GitLab CI Example

Hosted Agents

Credential Storage

Troubleshooting

The Approval Request Expired

”The request was denied”

The Browser Did Not Open

”Invalid API key” Error

Credentials Not Persisting

”Org mismatch” After Switching Accounts

​Log In

​Log In Without a Browser

​Getting an API Key

​Using the Key

​Legacy Browser Login

​Check Authentication Status

​Logout

​Environment Variable (CI/CD)

​Overriding with an Interactive Login

​GitHub Actions Example

​GitLab CI Example

​Hosted Agents

​Credential Storage

​Troubleshooting

​The Approval Request Expired

​”The request was denied”

​The Browser Did Not Open

​”Invalid API key” Error

​”Network error” During Login

​Credentials Not Persisting

​”Org mismatch” After Switching Accounts

Log In

Log In Without a Browser

Getting an API Key

Using the Key

Legacy Browser Login

Check Authentication Status

Logout

Environment Variable (CI/CD)

Overriding with an Interactive Login

GitHub Actions Example

GitLab CI Example

Hosted Agents

Credential Storage

Troubleshooting

The Approval Request Expired

”The request was denied”

The Browser Did Not Open

”Invalid API key” Error

”Network error” During Login

Credentials Not Persisting

”Org mismatch” After Switching Accounts