Skip to content
LogoLogo

How to authenticate the CLI

This guide shows you how to install the picked command and sign it in. Commands that read your organizations, projects, and workspaces then know who you are. It expects a Picked account and a project directory to work in.

1. Install the CLI

The binary is picked. Run it from the directory that holds your picked.config.ts, so it reads your configuration and writes your selection next to it.

2. Sign in

picked login

The command opens your browser for a one-time sign-in and prints your identity:

Opening your browser to sign in...
https://api.picked.app/…/oauth/authorize?…
Logged in as you@example.com (https://api.picked.app)

If your account must use MFA, the browser asks for the code from your authenticator app before it signs the CLI in. Picked staff, and members of an organization that requires MFA, must use it.

The CLI stores the session in ~/.picked/auth/<origin>.json. It refreshes the session as it nears expiry.

3. Confirm the session

picked whoami
you@example.com (https://api.picked.app)

Each command acts on the API origin your current directory resolves to, and on no other. To end the session for that origin:

picked logout
Logged out of https://api.picked.app.

Run the CLI in CI

picked generate types reads the workspace schema, not your account, so CI needs no session for it. A workspace you read with source: 'preview' needs that workspace's token. Run picked workspace use once on your machine, then give CI the two values it wrote:

PICKED_PROJECT_ID=your-project-id \
PICKED_PREVIEW_TOKEN=$YOUR_CI_SECRET \
picked generate types --check

picked workspace list and picked workspace use read your organizations and projects, so those two do need a session. Run them on your machine, where a browser can sign you in.