# Accedere con keenauth login

`keenauth login` ti fa accedere con il tuo account della dashboard, così puoi gestire i tuoi ambienti dal terminale senza creare una chiave API. Per i job di CI e gli script, continua a usare una chiave API in `KEENAUTH_API_KEY` (vedi [Interfaccia a riga di comando](/docs/cli)).

## Comandi

| Comando | Cosa fa |
|---|---|
| `keenauth login` | Accedi con il flusso del dispositivo: la CLI mostra un indirizzo e un codice, tu apri l'indirizzo su un dispositivo qualsiasi, accedi alla dashboard e inserisci il codice. |
| `keenauth login --web` | Accedi nel browser su questo computer. La CLI apre la pagina di accesso e riceve il risultato su `http://127.0.0.1:<port>/callback` (oppure `http://[::1]:<port>/callback`); la richiesta è protetta con PKCE (S256), `state` e il parametro `iss`. |
| `keenauth whoami` | Mostra l'utente con cui hai effettuato l'accesso, l'organizzazione e l'ambiente selezionato. |
| `keenauth env use <environment_id>` | Seleziona l'ambiente che i comandi successivi gestiranno. Il control plane verifica che tu abbia un ruolo nella dashboard per quell'ambiente. |
| `keenauth env list` | Elenca gli ambienti su cui puoi lavorare, dal control plane. L'ambiente selezionato con `env use` è contrassegnato con `*`. |
| `keenauth logout` | Revoca la sessione sul server e la rimuove da questo computer. |

```sh
keenauth login
keenauth env use env_01j9z3c0000000000000000000
keenauth users list
```

Quando `KEENAUTH_API_KEY` è impostata, ha sempre la precedenza; la sessione salvata viene usata solo se non è impostata alcuna chiave API.

## Elencare gli ambienti

`keenauth env list` chiede al control plane gli ambienti dell'account con cui hai effettuato l'accesso e nei quali hai un ruolo nella dashboard (`GET /v1/environments`, vedi [Elenca i tuoi ambienti per la CLI](/docs/api/control/environments/list)). Serve una sessione; se non ce l'hai, ti chiede di eseguire `keenauth login`.

| Flag | Descrizione |
|---|---|
| `--limit` | Dimensione della pagina, da 1 a 100 (predefinito 20). |
| `--after` | Il cursore stampato dalla pagina precedente (`more results: --after <cursor>`). |
| `--all` | Segue le pagine ed elenca tutti gli ambienti. |
| `-o table\|json\|yaml` | Formato di output; la tabella contrassegna l'ambiente selezionato con `*`, mentre in JSON e YAML ogni riga ha `current: true` per esso. |

Un cursore `--after` non valido o di un'altra sessione viene rifiutato (`invalid_cursor`); esegui di nuovo il comando senza di esso.

## Come funziona la sessione

- L'accesso emette un token di accesso di breve durata (5 minuti) e un refresh token (12 ore). Entrambi sono legati a una chiave DPoP (RFC 9449) creata su questo computer, quindi un token copiato non può essere usato da un'altra macchina. Il refresh token viene ruotato a ogni utilizzo.
- Per ogni comando la CLI chiede al control plane un token di gestione dell'ambiente selezionato. Questo token vale 10 minuti, è legato alla stessa chiave DPoP ed è mantenuto **solo in memoria**; non viene mai scritto su disco.
- Le richieste al tuo ambiente includono il token di gestione, una prova DPoP nuova e la tua identità nella dashboard. Il tuo ambiente verifica che tu abbia ancora un ruolo, quindi rimuovere il ruolo nella dashboard termina l'accesso della CLI entro pochi minuti.

## Dove viene salvata la sessione

| Cosa | Dove |
|---|---|
| Issuer, ID utente, organizzazione, impronta della chiave DPoP, ambienti selezionati | `config.json` in `KEENAUTH_CONFIG_DIR`, oppure in `keenauth` nella tua directory di configurazione utente (modalità 0600) |
| Refresh token e chiave privata DPoP | Il portachiavi del sistema operativo: Keychain di macOS (`security`) o Secret Service su Linux (`secret-tool`) |

I segreti vengono passati allo strumento del portachiavi tramite lo standard input, mai come argomenti del comando. Se nessun portachiavi è disponibile (per esempio su Windows, o su un server Linux senza Secret Service), `keenauth login` si interrompe con un errore. Puoi allora passare `--insecure-storage` per salvare il refresh token e la chiave privata DPoP non cifrati in `credentials.json` (modalità 0600), accanto a `config.json`. La CLI mostra un avviso: chiunque possa leggere quel file può agire al posto tuo finché la sessione non scade. Su macchine condivise preferisci una chiave API.

## Impostazioni

| Variabile | Predefinito | Descrizione |
|---|---|---|
| `KEENAUTH_LOGIN_ISSUER` | `https://login.keenauth.com` | Il server di accesso. Deve essere un indirizzo `https`. |
| `KEENAUTH_CONTROL_URL` | `https://api.keenauth.com/v1` | Il control plane che emette i token di gestione. Deve essere un indirizzo `https`. |
| `KEENAUTH_CONFIG_DIR` | la tua directory di configurazione utente + `keenauth` | Dove viene conservato `config.json` (e, con `--insecure-storage`, `credentials.json`). |

## Errori

| Messaggio | Cosa fare |
|---|---|
| `you are not signed in` / `your session has expired or was revoked` | Esegui di nuovo `keenauth login`. Codice di uscita 3. |
| `no environment is selected` | Esegui `keenauth env use <environment_id>`. |
| `environment … does not exist or you have no dashboard role in it` | Controlla l'ID nella dashboard o chiedi a un proprietario un ruolo. |
| `no OS keychain is available` | Installa un portachiavi, usa `--insecure-storage` oppure usa una chiave API. |