Sign in
A browser handshake puts a short-lived token in ~/.lly/credentials.
Authentication happens in the browser. The CLI never sees your password. lly login opens auth.lilylabs.io, the browser confirms the session, and the CLI receives a short-lived access token over a WebSocket. The token is written to ~/.lly/credentials with mode 0600 and used for every subsequent call that talks to the LILY platform.
The handshake
Run lly login. The CLI prints a six-character pairing code, opens your default browser to https://auth.lilylabs.io/cli?code=XXXX, and starts listening on a WebSocket back to the auth server. After you confirm in the browser, the auth server pushes the access token to the waiting CLI process, the CLI writes the credentials file, and the command exits.
The whole flow takes a couple of seconds. The browser tab closes itself once the auth server has the confirmation. If you already had a credentials file, it is replaced atomically — there is no intermediate state where the file is empty or world-readable.
When the browser cannot open
Headless boxes, SSH sessions, and minimal Docker images do not have an X server or a registered URL handler. Pass --print-url to skip the xdg-open step and copy the link manually into a browser on another machine.
The pairing code is bound to a single CLI process. It expires after ten minutes. Open the link on any device — phone, laptop, tablet — as long as it can reach auth.lilylabs.io. The CLI only needs an outbound WebSocket to receive the token, so it works behind most corporate proxies.
Token TTL and refresh
Access tokens live for twenty-four hours. Every authenticated CLI call checks the expiry stamp in ~/.lly/credentials and silently refreshes against the auth server when fewer than two hours remain. Refresh is a single round-trip and never opens a browser — only the initial pairing does. If the refresh token itself has been revoked (you signed out elsewhere, the account was suspended, or the device was removed in the platform UI) the next command will fail with auth: refresh rejected and prompt you to run lly login again.
Signing out
lly logout deletes the credentials file locally and revokes the refresh token on the server in one step. Run it on shared workstations before you walk away. Subsequent commands that do not require authentication — lly compile, lly run, lly bundle inspect — continue to work; only deploy and registry calls require a session.
Inspecting the session
lly config get auth.user prints the email on the active session without touching the token. lly doctor includes an auth probe that checks the credentials file permissions, expiry, and reachability of auth.lilylabs.io. If you suspect a stale token is causing a deploy to fail, run lly doctor first — it is faster than re-authenticating and will tell you exactly what is wrong.
With a session in place, you are ready to ship something. Compile a single source file with lly compile, package a Next.js project with the nextjs plugin, or jump straight to your first deploy.