Flowleap auth

FlowLeap Auth

Global flags and configuration: see flowleap-shared.

Commands

Login via OAuth device flow

flowleap auth login

Starts the OAuth 2.0 device flow: the CLI requests a device code from the backend, prints a user code plus verification URL (and opens the browser), then polls until the login is approved. The resulting session JWT is stored in ~/.config/flowleap/credentials.toml (mode 0600). No local callback server is involved, so it also works when the browser runs on another machine — open the printed URL and enter the user code there. When stdout is not a TTY, the browser auto-open and spinner are suppressed automatically.

Structured login for agents (--json)

flowleap --json auth login

With --json, auth login becomes a blocking process that speaks NDJSON on stdout — one compact JSON object per line, nothing else. It emits the device-authorization event immediately, then polls until the human approves and emits exactly one terminal event before exiting:

{"event":"device_authorization","verification_uri":"https://flowleap.co/device","verification_uri_complete":"https://flowleap.co/device?code=ABCD-1234","user_code":"ABCD-1234","expires_in":900,"interval":5}
{"event":"authorized","stored":true}

Terminal events: authorized (exit 0 — the session token is stored, same as the human flow) or failed with an error description (nonzero exit per the standard exit-code table — denied, expired, or another error). Structured mode has no side effects: no browser auto-open, no clipboard copy, no spinner — the agent decides what to do with the URL.

Agent-mediated sign-in sequence:

1. Run flowleap --json auth login in the background and read the first NDJSON line (the device_authorization event).
2. Relay verification_uri and user_code to the human (or open verification_uri_complete yourself when running on the human's own machine).
3. Await the process's terminal event. authorized means the session token is stored and authenticated commands work immediately; failed means start over.
4. Session tokens expire. For durability, follow up with flowleap --json auth create-token --name <name> --store to mint and store a long-lived fl_pat_ personal token.

Login with a personal API token

flowleap auth login --api-key fl_pat_your_token_here

Login with a session token

flowleap auth login --token eyJhbGci...

Personal API tokens (headless/agent use)

flowleap auth create-token --name my-agent --store   # mint + store (shown once)
flowleap auth tokens                                 # list tokens
flowleap auth revoke-token <id>                      # revoke by id

Personal tokens use the fl_pat_… format and are long-lived. Minting requires an OAuth session — API tokens cannot mint further tokens (backend-enforced).

Check Status

flowleap auth status

Shows: base URL, authentication method, default model, and user profile (if authenticated).

Logout

flowleap auth logout                # clear everything, including provider keys
flowleap auth logout --session-only # clear only the OAuth session token

Plain logout clears all stored credentials, including EPO/USPTO provider keys. Use --session-only to drop just the browser-session token — useful when an expired session token is shadowing a still-valid fl_pat_ API key (the CLI prefers the session token when both are stored).

The CLI self-heals this case: on a 401 with a stored session token, it retries once with the stored API key and prints a stderr warning suggesting logout --session-only. The fallback is skipped when the token was passed explicitly via --token or FLOWLEAP_TOKEN.

Environment Variable Override

Set FLOWLEAP_API_KEY (an fl_pat_… token) or FLOWLEAP_TOKEN to bypass stored credentials entirely. These take effect without running auth login.