| name | website-login |
| description | Use whenever the user needs to log in to a website on their phone and reuse that authenticated session locally, especially for Playwright storageState JSON, cookies/localStorage capture, MFA, SMS codes, passkeys, or mobile-first login flows that are awkward in headless automation. You run Cookey CLI in your current environment; the user signs in on their iPhone in the Cookey app; the relay only transports encrypted blobs. Trigger even if the user asks more loosely for help logging in, reusing an authenticated browser state, exporting cookies, or getting a local automation session from a phone login. |
Website login
You run the Cookey CLI in your current environment. The user completes the actual website login on their iPhone inside the Cookey app’s in-app browser—never on a browser you control remotely.
How it works
Cookey splits “where login happens” from “where automation runs”:
-
Local environment (cookey CLI + local daemon) — You run commands here. The CLI creates a short-lived login request, agrees cryptographic keys with the phone, and waits for an encrypted payload. After delivery, you export Playwright-compatible storageState JSON (cookies + origins / localStorage) for local scripts.
-
User’s iPhone (Cookey app) — The user scans the QR or taps the HTTPS jump link. The jump page opens the cookey:// deep link into the app. The app opens the target URL in its embedded browser. The user signs in like a normal mobile session (password, OTP, authenticator app, passkeys, etc.). The app reads cookies and storage, encrypts them, and uploads ciphertext to the relay.
-
Relay server — Only moves opaque encrypted blobs and request metadata. It is not trusted with plaintext cookies or credentials; design assumes zero-knowledge transport.
-
Result — The CLI decrypts locally and writes session material under ~/.cookey/. cookey session export strips Cookey-only metadata and outputs the same shape Playwright expects for browser.newContext({ storageState }).
Why use this: Many real sites are easier or only possible to log into on a phone (MFA apps, SMS, mobile-only UI). Cookey turns that authenticated mobile browser state into something local Playwright can load.
Install
npm install -g @cookey/cli
pip install cookey
Alternatively, download prebuilt binaries:
What you export
cookey session export writes standard Playwright storageState JSON:
Cookey keeps extra local metadata under ~/.cookey/; session export strips
that and emits only what Playwright consumes.
Quick workflow (you and the user)
-
You start a login request in your local environment:
cookey request start https://example.com/login --json --qr
-
The user scans the QR (or opens the link) on their iPhone with the Cookey app, then finishes login in the app’s browser.
-
You export after the session is delivered:
cookey session export --latest --out storageState.json --pretty
-
You (or the user’s code) load it in Playwright:
import { chromium } from "@playwright/test";
const browser = await chromium.launch();
const context = await browser.newContext({
storageState: "storageState.json",
});
const page = await context.newPage();
await page.goto("https://example.com/account");
You can also pipe to a file:
cookey session export r_xxxxxxxxxxxxxxxxxxxxxx > storageState.json
Required execution order
When you start or refresh a request for the user, follow this order:
- Run
cookey request start ... --json --qr or cookey request refresh ... --json --qr without --attach.
- Immediately reply to the user with the pair key, fingerprint, and QR code from the command output.
- Only after that reply is sent, wait for completion with
cookey request status <rid> --watch or poll until the request is ready.
- Export the session with
cookey session export.
If you skip step 2 and start waiting first, the user may never see the pair key in tool-call environments where terminal output is hidden.
What you must show the user
When you start or refresh a Cookey request for the user, paste the required values from the CLI into your reply before you wait for completion. Do not only mention that a login request was started.
- Always include the pair key as plain text.
- Always include the CLI fingerprint / verification string when the CLI prints it.
- Always include the CLI-provided
jump_link as a clickable HTTPS link.
- If you render the QR code using
--qr or --json --qr, always wrap the ASCII QR code in a text ... code block to prevent Markdown from destroying the line breaks. If using --json, the QR code is in the qr_text field with \n characters.
- Do not rely on a bare
cookey:// deep link as the primary user action; many chat surfaces will not expose it as a tappable link.
- The CLI-provided
jump_link is not enough by itself; still include the pair key and fingerprint alongside it.
- If using
--json, copy pair_key, cli_public_key_fingerprint, jump_link, and qr_text from the JSON output exactly.
The Cookey app on the user’s iPhone may ask them to type the pair key and confirm the fingerprint matches the terminal.
Use a reply shape like this:
- Pair key:
ABCD-1234
- Fingerprint:
xxxxxx
- Jump link:
https://...
- QR code:
<ascii qr code>
Important warning about --attach
Unless your tool-call environment keeps a detached process alive (e.g. nohup
or similar), do not use --attach. If the parent exits, verification can expire.
Default is detached: cookey request start / cookey request refresh spawns a background daemon and returns once the local descriptor exists. --attach blocks in the foreground until the session arrives.
For agent or tool-call environments where the user cannot directly inspect stdout, treat --attach as unsafe by default even if it technically works. It makes it too easy to block before you have echoed the pair key and fingerprint back to the user.
Command Reference
cookey request start <target_url>
Create a new login request for target_url, register it with the relay, print
the pair key / jump link, and start a local waiter process.
Flags:
--server URL override the relay server; must be https://--timeout SECONDS request lifetime in seconds; default 300, capped at 1800--qr render the cookey:// deep link as a terminal QR code--json emit machine-readable JSON instead of human-readable output--attach wait inline instead of launching a detached daemon--help print command usage
Examples:
cookey request start https://example.com/logincookey request start https://example.com/login --qrcookey request start https://example.com/login --json --qrcookey request start https://example.com/login --timeout 900 --server https://api.cookey.shcookey request start https://example.com/login --json
Notes:
- On success, the command prints a request ID (
rid), pair key, jump link, and
daemon PID. It also prints the CLI fingerprint / verification string when
available.
- Without
--attach, the command exits as soon as the detached daemon is ready
to wait for the encrypted session.
- In agent workflows, prefer
--json --qr, send the returned pair key / fingerprint / QR code to the user immediately, then watch status in a separate step.
cookey request refresh <target_url>
Create a refresh request for target_url using the latest local session for the
same target as seed state.
Flags:
- Same flags as
cookey request start
Examples:
cookey request refresh https://example.com/logincookey request refresh https://example.com/login --qrcookey request refresh https://example.com/login --json --qrcookey request refresh https://example.com/login --attach
Notes:
- A previous local session for the same target is required. If none exists,
Cookey returns:
no previous session found for this target; run cookey request start first
- If the stored session contains device info, Cookey includes APNs metadata so
the mobile app can be nudged directly.
- Refresh merges new cookies and local storage over the previously stored state,
preserving missing values from the older session when needed.
- If the previous session does not contain device info, refresh still works, but
the user must complete the flow from QR / pair key instead of push-assisted delivery.
cookey request status [rid]
Inspect local request state. If there is no local record for the requested rid,
Cookey falls back to relay status using the configured default server.
Flags:
--latest inspect the most recently updated local request or session--watch poll once per second until a terminal state is reached--json emit machine-readable JSON--help print command usage
Examples:
cookey request statuscookey request status r_xxxxxxxxxxxxxxxxxxxxxxcookey request status --latestcookey request status --latest --watchcookey request status r_xxxxxxxxxxxxxxxxxxxxxx --json
Status values:
waiting daemon is alive and waiting for the encrypted sessionreceiving session arrived and is being decrypted / written locallyready session file exists and is exportableexpired request lifetime ended before a usable session was writtenorphaned daemon descriptor says the request was active, but the daemon process is goneerror the daemon failed while waiting, decrypting, or writingmissing no local or remote record was found
Notes:
cookey request status with no rid and no --latest returns a summary of
the latest daemon and latest session.--watch requires either an explicit rid or --latest.
cookey session export [rid]
Export a local session as Playwright storageState JSON.
Flags:
--latest export the newest local session--out FILE write to FILE instead of stdout--pretty pretty-print JSON with indentation--help print command usage
Examples:
cookey session export --latest > storageState.jsoncookey session export --latest --out storageState.json --prettycookey session export r_xxxxxxxxxxxxxxxxxxxxxx
Notes:
- If
--out is relative, it is resolved against the current working directory.
- If the session file is missing but a daemon descriptor exists, Cookey reports
the descriptor status so you can tell
expired from error.
- The exported file is suitable for Playwright's
browser.newContext({ storageState }).
cookey session list
List all locally known request IDs, newest first, using the newest timestamp from
either the daemon descriptor or the exported session file.
Flags:
--json emit machine-readable JSON--help print command usage
Examples:
cookey session listcookey session list --json
cookey session delete <rid>
Delete the local session file and daemon descriptor for rid.
Flags:
--json emit machine-readable JSON--help print command usage
Examples:
cookey session delete r_xxxxxxxxxxxxxxxxxxxxxxcookey session delete r_xxxxxxxxxxxxxxxxxxxxxx --json
Notes:
- Cookey refuses to delete an active request whose daemon is still in
waiting
or receiving state.
cookey session clean
Delete all inactive local request/session pairs.
Flags:
--json emit machine-readable JSON--help print command usage
Examples:
cookey session cleancookey session clean --json
Notes:
- Active requests are skipped instead of force-killed.
cookey config get [key]
Read configured defaults from ~/.cookey/config.json.
Supported keys:
default-servertimeout-secondssession-retention-days
Aliases:
server -> default-servertimeout -> timeout-secondsretention-days -> session-retention-days
Flags:
--json emit machine-readable JSON--help print command usage
Examples:
cookey config getcookey config get default-servercookey config get timeout --json
cookey config set <key> <value>
Persist configured defaults in ~/.cookey/config.json.
Flags:
--json emit machine-readable JSON--help print command usage
Examples:
cookey config set default-server https://api.cookey.shcookey config set timeout-seconds 900cookey config set retention-days 30 --json
Notes:
default-server must parse as a relay base URL and must use https.timeout-seconds must be a positive integer.session-retention-days is stored in config today, but the current CLI does
not automatically delete sessions based on that value. Use session clean for
explicit cleanup.
Additional Behavior Details
- Every CLI entry point bootstraps
~/.cookey/, ensures the keypair exists,
ensures device ID exists, and cleans up stale daemon descriptors.
- Request/session JSON under
~/.cookey/ is written atomically.
- User-facing commands return exit code
0 on success and 1 on CLI/validation errors.
- Inline daemon execution used by
--attach can also return:
3 when the request expires before session delivery5 when the daemon encounters a relay, decrypt, or local write failure
Suggested automation patterns (you)
Detached start + watch:
cookey request start https://example.com/login --qr
cookey request status --latest --watch
cookey session export --latest --out storageState.json --pretty
JSON-first scripting (Note: If you need to show the QR code to the user while using JSON output, use --json --qr and extract the qr_text field, formatting it carefully inside a ```text block):
cookey request start https://github.com/login --json --qr
cookey request status --latest --json
cookey session export --latest --out storageState.json
(Tip: When testing the login flow, avoid stateless domains like example.com which will yield an empty session. Use a real site like github.com/login or x.com/login to verify cookies and localStorage are captured correctly.)
Playwright usage:
import { chromium } from "@playwright/test";
const browser = await chromium.launch();
const context = await browser.newContext({
storageState: "storageState.json",
});
