# Interfaccia a riga di comando L'interfaccia a riga di comando `keenauth` (CLI) chiama la management API da un terminale o da uno script. Ogni comando incapsula un metodo tipizzato dell'SDK Go, quindi CLI e API si comportano allo stesso modo. Non esiste ancora un pacchetto di installazione. ## Autenticazione e destinazione La CLI legge le credenziali solo dall'ambiente. La chiave API non viene mai accettata come flag, così non finisce nella cronologia della shell. | Variabile | Obbligatoria | Descrizione | |---|---|---| | `KEENAUTH_API_KEY` | sì | Chiave della management API. Se manca, il comando termina con codice 3. | | `KEENAUTH_BASE_URL` | sì, a meno che `--base-url` non sia impostata | URL base della management API del tuo ambiente. | Invece di una chiave API puoi accedere con l'account della dashboard: `keenauth login`, poi `keenauth env use `. La sessione viene usata solo quando `KEENAUTH_API_KEY` non è impostata, e in tal caso l'indirizzo dell'ambiente proviene dal control plane (vedi [Accesso con keenauth login](/docs/cli/login)). Il flag `--base-url` sovrascrive `KEENAUTH_BASE_URL` per un singolo comando. La CLI non stampa mai la chiave API; se una risposta del server la riporta, viene sostituita con `[redacted]`. ## Comandi I comandi seguono il modello `keenauth [arguments] [flags]`. Esegui `keenauth --help` o `keenauth --help` per l'elenco completo. | Gruppo | Azioni | |---|---| | `users` | `list`, `search`, `get`, `create`, `update`, `delete`, `block`, `unblock`, `cancel-deletion`, `authenticators list`, `authenticators delete`, `authenticators reset`, `authenticators reactivate`, `send-password-reset`, `send-verification-email`, `emails send-verification`, `start-recovery`, `logs list` | | `applications` | `list`, `create`, `get`, `update`, `delete`, `get-api-grant`, `put-api-grant`, `delete-api-grant`, `credentials list`, `credentials create`, `credentials delete` | | `apis` | `list`, `create`, `get`, `update`, `delete` | | `connections` | `list`, `create`, `get`, `update`, `delete`, `activate`, `deactivate` | | `identity-settings` | `get`, `update` | | `environment-settings` | `get`, `update` | | `config` | `export` (senza `-o` stampa YAML), `plan -f ` (stampa un diff leggibile in un terminale), `plans get`, `apply ` (chiede conferma; `--secrets-from-env` legge i segreti dalle variabili d'ambiente, `--confirm-deletion /`), `promote --from --to ` (esporta, pianifica, mostra il diff e applica dopo conferma; vedi [Promozione della configurazione con keenauth config promote](/docs/cli/config-promote)) | | `api-keys` | `list`, `get`, `create`, `rotate`, `revoke` | | `logs` | `list`, `get`, `tail` (segue i nuovi record; `--type`, `--user`, `--org`; vedi [Seguire i log con keenauth logs tail](/docs/cli/tail)) | | `support-access-grants` | `list`, `get`, `create`, `delete` (vedi [Concedere accesso al supporto con keenauth support-access-grants](/docs/cli/support-access-grants)) | | `directories` | `simulate --scenario ` (esegue uno scenario del simulatore SCIM in sviluppo e staging; vedi [Testare il provisioning SCIM con keenauth directories simulate](/docs/cli/directories-simulate)) | | `audit` | `verify` (verifica offline un export di audit scaricato; vedi [Verificare gli export di audit con keenauth audit verify](/docs/cli/audit-verify)) | | `branding` | `get`, `update`, `applications get`, `applications put`, `organizations get`, `organizations put`, `css put`, `page-template put`, `publish`, `rollback`, `versions list`, `texts get`, `texts put`, `texts delete` | | `signing-keys` | `list`, `rotate`, `policy get`, `policy update` | | `events` | `tail` (segue gli eventi dei clienti tramite l'API eventi; vedi [Seguire gli eventi con keenauth events tail](/docs/cli/events-tail)), `get ` (un solo evento, esattamente come inviato dal server) | | `mock` | `serve` avvia un server OIDC mock locale per i test offline; non richiede una chiave API (vedi [Server mock locale](/docs/cli/mock-server)) | | `test` | `login --user <+test address>` accede a un ambiente `development` con un utente di test usando il codice fisso e stampa i token; non richiede una chiave API (vedi [Accesso degli utenti di test con keenauth test login](/docs/cli/test-login)) | | `webhooks` | `listen --forward-to ` inoltra gli eventi di un ambiente `development` o `staging` alla tua macchina, firmati con un segreto temporaneo (vedi [Testare i webhook in locale con keenauth webhooks listen](/docs/cli/webhooks-listen)) | | `login`, `logout`, `whoami`, `env` | `login` (`--web`, `--insecure-storage`), `logout`, `whoami`, `env use `, `env list`: accedi con il tuo account della dashboard invece di una chiave API (vedi [Accesso con keenauth login](/docs/cli/login)) | I comandi di elenco accettano `--limit`, `--after`, `--before` e `--order`. Quando esistono altri risultati, il cursore successivo viene stampato su stderr come `more results: --after `. ## Formato di output `--output` (`-o`) seleziona `table`, `json` o `yaml`. Senza il flag la CLI stampa una tabella su un terminale e JSON altrimenti. JSON e YAML contengono la risposta dell'API invariata e non vengono mai tradotti, così gli script possono farvi affidamento. I risultati vanno su stdout; errori, suggerimenti e la riga `etag` vanno su stderr. ## Corpi delle richieste I comandi che inviano un corpo accettano un flag per ogni campo piatto, con il nome della chiave JSON e trattini (`phone_number` diventa `--phone-number`). Gli oggetti annidati si passano con `--data`: - `--data @file.json` legge il corpo da un file. - `--data -` legge il corpo dallo standard input. I flag sovrascrivono i campi del file. Un corpo è limitato a 4 MiB. ```sh keenauth users create --email ada@example.com keenauth apis create --data @api.json echo '{"name":"Orders"}' | keenauth apis update api_123 --data - --if-match '"v3"' ``` ## Concorrenza ottimistica: `--if-match` e l'etag I comandi di aggiornamento ed eliminazione per applicazioni, API e connessioni richiedono `--if-match`; `users update` lo accetta. Il valore è il `ETag` della versione che vuoi modificare. Il server rifiuta la richiesta se la risorsa è cambiata nel frattempo. `identity-settings update` lo richiede a sua volta. `environment-settings update` lo richiede a sua volta. Anche le scritture della bozza di branding (`branding update`, `branding applications put`, `branding organizations put`, `branding css put`, `branding page-template put`) lo richiedono. Ogni comando `get` (`users`, `applications`, `apis`, `connections`, `identity-settings`, `environment-settings`) stampa su stderr l'intestazione `ETag` della risposta, così stdout resta pulito: ```sh $ keenauth apis get api_123 { ... } etag: "v3" $ keenauth apis update api_123 --name Orders --if-match '"v3"' ``` La riga `etag` non viene aggiunta all'output JSON o YAML. ## Comandi distruttivi e `--yes` I comandi che eliminano o bloccano chiedono conferma (`[y/N]`) su un terminale. Rifiutare termina con codice 1 e stampa `aborted`. Quando lo standard input non è un terminale, il comando si rifiuta di essere eseguito a meno che non passi `--yes` (`-y`); termina con codice 2 prima di inviare qualsiasi richiesta. ## Codici di uscita | Codice | Significato | |---|---| | `0` | Successo. | | `1` | Errore del server o operativo, conferma rifiutata o errore di rete. | | `2` | Errore di utilizzo: comando o flag sconosciuto, argomento mancante, corpo non valido, oppure `--yes` mancante su un terminale non interattivo. | | `3` | Errore di autenticazione: la chiave manca oppure il server ha risposto 401 o 403. | | `4` | Il piano non include la funzionalità (`403` con `plan_feature_unavailable`). | Per gli errori del server la CLI stampa su stderr `error`, `code`, `status`, `detail`, `request_id` e una riga `field` per ogni errore di validazione. Indica il `request_id` quando contatti il supporto. ## Lingua Il testo leggibile (aiuto, richieste, errori, intestazioni delle tabelle) è disponibile in turco (`tr`), inglese (`en`), francese (`fr`), tedesco (`de`), coreano (`ko`), giapponese (`ja`), italiano (`it`) e spagnolo (`es`). La lingua è presa dalla prima di queste variabili impostata: `KEENAUTH_LANG`, `LC_ALL`, `LC_MESSAGES`, `LANG` (ad esempio `tr_TR.UTF-8` seleziona `tr`). Un valore vuoto o non supportato seleziona l'inglese, e un messaggio mancante in una lingua ricade sull'inglese. L'output leggibile dalle macchine non viene mai tradotto: nomi e valori dei campi JSON e YAML, il problema `code` e le etichette `code`, `status` e `request_id` restano invariati in ogni lingua. I messaggi provenienti dal server vengono mostrati così come il server li ha inviati. ```sh KEENAUTH_LANG=de keenauth users list --help ``` ## Credenziali dell'applicazione `keenauth applications credentials list|create|delete` gestisce i client secret e le chiavi pubbliche registrate di un'applicazione. Questi comandi non usano `--if-match`. ```sh keenauth applications credentials create app_123 --type client-secret --expires-at 2027-01-01T00:00:00Z keenauth applications credentials create app_123 --type public-key --jwk-file key.pub.jwk keenauth applications credentials delete app_123 cred_456 --yes ``` Un client secret viene stampato una sola volta, su stdout, insieme a un avviso una tantum su stderr. `--jwk-file` accetta un singolo JWK pubblico (al massimo 16 KiB); un file con membri privati viene rifiutato prima di inviare qualsiasi richiesta. ## Chiavi API `keenauth api-keys list|get|create|rotate|revoke` gestisce le chiavi della management API dell'ambiente. Questi comandi non usano `--if-match`. ```sh keenauth api-keys create --name ci --type restricted --permissions users:read,users:write --expires-at 2027-10-01T00:00:00Z keenauth api-keys rotate key_123 --overlap-hours 24 keenauth api-keys revoke key_123 --reason leaked --yes ``` La chiave grezza di `create` e `rotate` viene stampata una sola volta, su stdout, insieme a un avviso una tantum su stderr; non può essere recuperata di nuovo. `list` e `get` stampano solo i metadati.