Connect the CLI for Cloud Authentication Profiles

Playrunner Cloud cannot open a browser on your computer directly. The Playrunner CLI provides an outbound-only authentication companion that pairs your computer with your Cloud account, opens native Chrome locally, and sends the captured browser state back to the Authentication Profile you selected.

The companion receives only Authentication Profile capture requests. It does not accept inbound network connections or receive your Playrunner API token.

To execute tests on a connected machine, use the separate local worker setup. auth connect handles browser capture; worker connect supplies test compute. Both use device pairing, but one process does not replace the other.

Requirements

You need:

• Node.js 20 or later.
• Google Chrome or a compatible Chromium browser installed on the computer where you will sign in.
• Playrunner CLI 0.2.5 or later.
• A signed-in account at playrunner.cloud.

Install the CLI globally on the computer that will perform authentication:

npm install --global playrunner@latest
playrunner --version

You do not need PLAYRUNNER_API_KEY for pairing or capturing an Authentication Profile.

Step 1 — Pair the computer

Run:

playrunner login

The CLI prints a short pairing code and opens the Playrunner Cloud approval page. If the page does not open automatically, copy the URL printed in the terminal into your browser.

1. Sign in to Playrunner Cloud if prompted.
2. Confirm that the code on the page exactly matches the code in your terminal.
3. Click Approve device.
4. Return to the terminal and wait for the paired confirmation.

For another Playrunner installation, specify its URL explicitly:

playrunner login --url https://your-playrunner.example.com

Pairing credentials are stored for the current operating-system user. On macOS, secret material is stored in Keychain when available. The companion configuration file is restricted to the current user.

Step 2 — Connect the companion

For an interactive capture, keep this command running in a terminal:

playrunner auth connect

The terminal should print:

Playrunner authentication companion is connected.

Leave that terminal open while creating or reauthenticating a profile. The computer appears as Online in the Paired devices panel within about 30 seconds. You can click Refresh to update the list immediately.

Optional advanced service mode

playrunner auth install is not an additional setup step and does not replace playrunner login. It is an optional way to keep the companion process running as a user-level background service:

playrunner auth install

For interactive captures, use the foreground playrunner auth connect command so you can respond to the terminal prompt after signing in. Most users should use only the two-step login, then auth connect flow described above.

Step 3 — Select the device in Cloud

1. Open Authentication Profiles in Playrunner Cloud.
2. Find the Paired devices panel.
3. Confirm that your computer is marked Online.
4. Choose it under Device for authentication.

The selection is stored in that browser. If the computer is offline, run playrunner auth connect, wait for the connected message, and refresh the device list.

Step 4 — Capture an Authentication Profile

Create a profile as described in the Authentication Profiles tutorial, then:

1. Click Authenticate on the profile.
2. Wait for Chrome to open on the paired computer.
3. Complete the normal sign-in flow, including single sign-on or multifactor authentication when required.
4. Confirm that the configured success URL or element is present.
5. Leave Chrome open and return to the companion terminal.
6. Press Enter in the terminal.
7. Wait for Authentication Profile capture completed. in the terminal and for the Cloud profile status to become Authenticated.

If the success condition is not satisfied, capture fails without replacing a previously stored session. Correct the profile's success condition or finish sign-in, then authenticate again.

Check or disconnect a device

Check whether the current computer is paired and recently online:

playrunner auth status

Stop the installed service, revoke the device in Cloud, and delete its local pairing credentials:

playrunner auth disconnect

You can also revoke another computer with the trash button in the Paired devices panel. Revocation prevents that device from receiving new capture requests. Run playrunner login again if you later want to pair it again.

After capture

The authentication companion is needed only to capture or refresh an Authentication Profile. After the profile becomes Authenticated, you may stop playrunner auth connect and turn off the paired computer if it is not also running tests. If the same machine supplies test compute, keep its separate worker connect process and Docker running.

Workflows using the Playrunner Cloud runner receive the stored state through a sealed, execution-bound handoff; they do not contact the companion or open a browser on your computer. Playrunner Cloud does not provide a separate session-test action. Attach the profile to a Playwright node and run the workflow to verify it through the real Playrunner Cloud runner execution path.

Security and captured data

The companion uploads Playwright browser storage state rather than your password or a single session ID. This state can include cookies, local storage, and IndexedDB data for the captured origins. A usable copy may allow someone to act as the signed-in account without entering its password or completing multifactor authentication again, so treat it as a password-equivalent credential.

The companion connects outbound over HTTPS. Its requests are signed with the paired device key, and capture uploads use short-lived capabilities. Captured state is encrypted at rest by Playrunner Cloud and omitted from normal profile API responses. During a workflow, only the authorized execution and selected Playwright node receive the state through a sealed handoff.

Revoking a paired device prevents it from receiving new capture requests. Revoking or deleting an Authentication Profile removes Playrunner's stored copy, but it cannot invalidate a copy obtained earlier. If exposure is suspected, also revoke active sessions in the target application or identity provider.

Troubleshooting

Symptom	What to do
playrunner: command not found	Install the CLI globally, then open a new terminal.
The pairing code expires	Run playrunner login again and approve the new code.
The device shows Offline	Run playrunner auth connect, leave it running, and refresh the device list.
Chrome does not open	Install Chrome or Chromium on the paired computer and retry.
Capture waits indefinitely	Return to the companion terminal and press Enter after sign-in is complete.
Capture reports a validation failure	Make sure the configured success URL or selector is present before pressing Enter.
The wrong computer opens Chrome	Select the intended online device in the Paired devices panel before clicking Authenticate.
The device is revoked	Run playrunner auth disconnect, then pair it again with playrunner login.