Connect from a terminal

On this page

alg connect (printed as npx agent-led-growth connect in the quickstart) gets a project key without copying a key. It prints a code and opens /connect; signed in, you type the code from your terminal. The page then shows when and from where the login was started (city and country, and the address cut to its network), the user agent, the name the program gave (which nothing checks) and your workspace. Only approve a login you started yourself in the last few minutes. Pick a project (or make a new one) and approve; the CLI then receives a new key bound to that project that can send events and handoffs and nothing else. A link that carries a code does not skip typing it, so nobody can send you a link that approves their login. After 10 wrong codes in 15 minutes, from one workspace or one address, codes are refused until the 15 minutes end. The flow it uses:

  • POST /v1/connect/start with { "client": "agent-led-growth" } answers 201 with device_code (the CLI's secret), user_code (XXXX-XXXX, for the person to type), verification_url (/connect, with no code), expires_in (600 seconds) and interval (3 seconds).
  • POST /v1/connect/poll with { "device_code": "…" }, every interval seconds, answers 202 { "status": "pending" } until you decide, 429 { "error": "slow_down" } when polled faster, 200 { "key", "project_id", "project_name", "endpoint" } once after approval, 403 { "error": "denied" } after Deny, and 410 { "error": "expired" } after 10 minutes or once the key was collected.

An agent uses the same two requests to read a project its person already has, without anyone pasting a key: send "scopes": ["read"] with the start ({ "client": "claude-code", "scopes": ["read"] }), show the person verification_url and user_code, and poll. The approve page then says, first and in bold, that the key can read the reports of the project they pick. scopes is optional and drawn from events (send events) and read (read that project's reports); left out it is ["events"], and both answers are exactly as above. When it is sent, both answers also carry scopes. write cannot be asked for: a device login can never delete data, change forwarding or manage projects.

Track stores only hashes of both codes, with the coarse place and the user agent of the start request, and deletes the login a day after it expires. It makes the key at the moment the CLI collects it, so the key is never stored anywhere waiting to be picked up. The key is labelled alg connect: <client> in Settings.