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.

Invece di una chiave API puoi accedere con l'account della dashboard: keenauth login, poi keenauth env use <environment_id>. 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).

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 <group> <action> [arguments] [flags]. Esegui keenauth --help o keenauth <group> --help per l'elenco completo.

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 <cursor>.

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.

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:

$ 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

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.

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.

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.

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.