Riferimento della CLI LogBrew: comandi e filtri

La CLI open source di LogBrew legge la telemetria e gestisce i dati dell’account da un terminale. Inizia dalla guida alla CLI per installazione, accesso e attività comuni.

Come funziona la CLI

In un terminale usa il testo leggibile. In script e agenti di codifica usa --json. Per le letture dell’account serve l’accesso con l’account. Prima di avviare un accesso, esegui logbrew status --json. Una persona deve completare l’autorizzazione nel browser. Le chiavi di ingestione del progetto inviano telemetria. Non possono sostituire l’accesso con l’account. La creazione di progetti e chiavi, le modifiche a stato, priorità e assegnatario dei problemi, i deploy e gli aggiornamenti delle segnalazioni modificano i dati dell’account. Prima di eseguire uno di questi comandi, verifica che l’azione e la destinazione siano corrette. Esegui logbrew --help per vedere tutti i comandi. Aggiungi --help a un comando, come logbrew read logs --help, per vederne i flag. Esegui logbrew help json per le regole del JSON.

Famiglia di comandi	Scopo
`login`, `whoami`, `me`, `logout`	Avvia l’accesso, legge l’identità dell’account o chiude la sessione locale.
`status`, `health`, `doctor`, `version`, `examples`	Legge l’accesso, lo stato di preparazione del progetto, la versione della CLI o gli esempi per il primo avvio.
`setup`	Legge i manifest locali e stampa un piano di configurazione dell’SDK. Non modifica file e non esegue il comando di installazione.
`projects`	Legge il catalogo dei progetti attivi.
`projects repositories`	Legge i repository collegati o rileva i componenti in un repository.
`projects create`, `projects keys create`	Crea un progetto o una chiave di ingestione per un progetto esistente.
`projects setup`	Registra la configurazione osservata per un progetto esistente.
`projects archive`, `projects delete`	Archivia un progetto o lo elimina definitivamente dopo una conferma.
`usage`, `account usage`	Legge utilizzo, limiti, stato della quota e date di azzeramento.
`mcp grants`, `mcp revoke`	Elenca per nome i client MCP collegati al tuo account o revoca una connessione.
`read`	Legge log, problemi, azioni, release, metriche, tracce o un singolo elemento.
`explain`	Legge prove limitate per un problema, un log, un’azione, una traccia, uno span, una metrica o una release.
`investigate issue`	Legge le prove dell’indagine su un problema o verifica un deploy candidato.
`issues archive`, `issues resolve`, `issues reopen`	Imposta lo stato di 1 problema o di massimo 100 problemi in un progetto.
`issues priority`	Imposta la priorità di 1 problema o di massimo 100 problemi in un progetto.
`issues assign`, `issues unassign`	Imposta o rimuove l’assegnatario, un account o un team, di 1 problema o di massimo 100 problemi in un progetto.
`issues assignees`	Elenca gli account e i team a cui puoi assegnare problemi in un progetto.
`issues owners`	Elenca i referenti suggeriti di 1 problema.
`issues ownership`	Legge o imposta le regole dei referenti e il file CODEOWNERS di un progetto.
`issues activity`	Legge la cronologia delle modifiche di 1 problema.
`issues rule`, `logs rule`	Imposta la regola di gravità di 1 problema o di 1 firma di log.
`inbox`	Legge i problemi che altre persone hanno assegnato a te o ai tuoi team, oppure li segna come letti.
`set issue`, `resolve`, `close`, `ignore`, `reopen`	Imposta lo stato di 1 problema. `close` significa `resolved`. `ignore` e `ignored` significano `archived`.
`deploy`	Registra un deploy completato.
`debug-artifacts`	Carica file di debug nativi Apple o Android, oppure cerca l’identità di un’immagine.
`analytics`	Legge panoramica, proprietà, confronti, percorsi, funnel, fidelizzazione o ciclo di vita.
`support`	Crea, legge, chiude o riapre le segnalazioni e invia risposte.
`watch`	Trasmette in tempo reale log, problemi o azioni.

Leggi il report di diagnostica di un progetto

Usa un ID progetto preso da logbrew projects --json:

logbrew doctor --project "<project_id>" --json

Il comando legge lo stato del progetto e un log recente. Non crea un progetto, non modifica una chiave e non registra la configurazione. Il report contiene status, checks e next. Ogni controllo contiene check, status e next. I controlli sono api, auth, project, ingest_key, setup, telemetry e logs. Il codice di uscita 0 significa che la CLI ha scritto un report. Non significa che il progetto sia pronto. Leggi lo status del report e ogni controllo. Un controllo not_checked non conta come superato.

`status` del report	Significato e passaggio successivo
`auth_invalid`	L’accesso all’account manca o non è valido. Una persona esegue `logbrew login`.
`project_missing`	Questo account non può accedere al progetto. Usa un ID da `logbrew projects --json`.
`api_unreachable`	La richiesta API non si è conclusa. Controlla la connessione di rete, poi esegui di nuovo il comando.
`check_failed`	Una richiesta non è riuscita o la sua risposta non era valida. Esegui di nuovo il comando senza modifiche. Se non riesce di nuovo, invia una segnalazione.
`needs_ingest_key`	Il progetto non ha una chiave di ingestione attiva. Crea una chiave solo se hai il permesso di modificare il progetto.
`needs_setup`	Serve la configurazione dell’SDK. Segui la guida rapida.
`needs_telemetry`	La configurazione è iniziata, ma LogBrew non ha telemetria per il progetto. Invia un evento di test.
`ready`	Il progetto ha una chiave attiva e telemetria. Leggi il segnale che ti serve per la tua attività.

Quando la lettura del progetto riesce, il controllo logs vale visible, empty, unavailable, error o invalid_response. Questo controllo non cambia lo status del report. Un risultato vuoto dei log non dice nulla sugli altri segnali. Una lettura non riuscita non è un risultato vuoto. Usa next come indicazione per il ripristino. Non dà il permesso di modificare lo stato dell’account o del progetto.

Esempio: accesso all’account mancante

Senza credenziali dell’account, il comando non esegue richieste API. Scrive questo report sull’output standard ed esce con codice 0:

{
  "checks": [
    { "check": "api", "next": "run the API reachability check first", "status": "not_checked" },
    { "check": "auth", "next": "run logbrew login", "status": "missing" },
    { "check": "project", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "ingest_key", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "setup", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "telemetry", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "logs", "next": "resolve the prior check first", "status": "not_checked" }
  ],
  "next": "run logbrew login",
  "status": "auth_invalid"
}

Questo report è diverso dalla diagnosi del progetto tramite API. Non contiene i campi API state, setup_status o next_action.

Filtri

Filtro	Comandi
`--project <project_id>`	logs, issues, actions, releases, metrics, traces, trace
`--release <release>`	logs, issues, actions, releases, metrics, traces, trace
`--environment <environment>`	logs, issues, actions, releases, metrics, traces, trace
`--service <service_name>`	logs, issues, actions, releases, metrics, traces
`--since 24h`	logs, issues, actions, releases, metrics, traces, analytics
`--until <RFC3339>`	logs, issues, actions, releases, metrics, traces, analytics
`--limit 100`	logs, issues, actions, releases, metrics, traces
`--severity error`	logs, watch
`--search checkout`	logs
`--trace <trace_id>`	logs
`--status unresolved`	issues (`unresolved`, `resolved`, `archived`)
`--priority high`	issues (`high`, `medium`, `low`)
`--assignee me`	issues (`me`, `none`, `my_teams`, un ID utente o `team:<team_id>`)
`--status error`	traces (`error`, `ok`)
`--min-duration-ms <milliseconds>`	traces
`--name <name>`	actions, metrics
`--user <distinct_id>`	actions

--since accetta una durata come 24h o 7d, oppure un timestamp RFC 3339. --until accetta un timestamp RFC 3339. È un orario di fine escluso e deve essere successivo a --since. La lettura di un singolo problema per ID non accetta --until. La gravità dei log vale info, warning, error o critical. Lo stato del problema è lo stato del flusso di lavoro del problema, non la sua gravità. --status ignored è un nome precedente di --status archived. --status open significa unresolved e --status closed significa resolved. --assignee none seleziona i problemi senza assegnatario e --assignee my_teams seleziona i problemi dei tuoi team. Qualsiasi altro valore di --assignee non riesce con invalid_assignee. La CLI accetta anche questi alias: --project-id, --env, --service-name, --trace-id, --distinct-id e --level per --severity. Nei nuovi script usa i nomi della tabella. Questo comando legge gli errori di 1 giorno:

logbrew read logs --severity error \
  --since 2026-10-01T00:00:00Z --until 2026-10-02T00:00:00Z --json

L’ID del progetto seleziona il progetto. Il nome del servizio seleziona un componente in quel progetto. Racchiudi tra virgolette i valori che contengono spazi:

logbrew read logs --project "<project_id>" \
  --service checkout-api --since 24h \
  --severity error --search "checkout failed" --json

Per un testo di ricerca che inizia con un trattino, inserisci -- prima del testo:

logbrew logs --json -- --timeout

Seleziona un’occorrenza del problema

Un problema raggruppa le occorrenze corrispondenti. Leggi il problema per conoscerne lo stato, il numero di occorrenze e gli orari di prima e ultima occorrenza:

logbrew read issue "<issue_id>" --json

Usa explain issue o investigate issue per le prove di una singola occorrenza. Senza --occurrence, LogBrew seleziona l’occorrenza consigliata. Non è sempre l’evento più recente. Per leggere l’evento più recente:

logbrew explain issue "<issue_id>" --occurrence latest --json

--occurrence accetta anche recommended, first o un ID occorrenza restituito da LogBrew. Questi comandi rifiutano i filtri di progetto, release, ambiente e tempo. Prima di confrontare le prove, leggi il timestamp dell’occorrenza selezionata. Consulta Indaga su un problema per i campi delle prove.

Cambia stato e priorità dei problemi

Usa 1 ID problema per modificare 1 problema:

logbrew issues archive "<issue_id>" --json
logbrew issues priority high "<issue_id>" --json

archive imposta archived, resolve imposta resolved e reopen imposta unresolved. La priorità vale high, medium o low. Una priorità impostata da te resta fissa. Altrimenti, la priorità segue la gravità del problema. Per modificare più di 1 problema, aggiungi --project. Tutti i problemi devono essere in quel progetto. Un comando modifica fino a 100 problemi:

logbrew issues resolve "<issue_id_1>" "<issue_id_2>" \
  --project "<project_id>" --json

Il risultato ha 1 voce per ogni problema. Ogni voce vale updated, unchanged o not_found. Un problema unchanged aveva già il valore richiesto. Puoi eseguire di nuovo lo stesso comando dopo un errore di rete. Questi comandi non chiedono conferma. Controlla prima gli ID dei problemi. Le letture e le modifiche dei problemi mostrano archived invece di ignored, e la priority, la priority_source e l’assignee di ogni problema. Consulta la risposta dei problemi.

Assegna i problemi

Un problema ha 0 o 1 assegnatario: un account o un team. Elenca gli account e i team che puoi assegnare in un progetto:

logbrew issues assignees --project "<project_id>" --json

Assegna 1 problema a un account, a te stesso con me oppure a un team:

logbrew issues assign "<user_id>" "<issue_id>" --json
logbrew issues assign me "<issue_id>" --json
logbrew issues assign "team:<team_id>" "<issue_id>" --json

Rimuovi l’assegnatario:

logbrew issues unassign "<issue_id>" --json

Aggiungi --project per modificare fino a 100 problemi di quel progetto, come per stato e priorità. Un account deve poter leggere il progetto e un team deve appartenere all’organizzazione del progetto. Per trovare i problemi assegnati a te o ai tuoi team:

logbrew read issues --project "<project_id>" --assignee my_teams \
  --status unresolved --json

L’output testuale mostra il nome dell’assegnatario, oppure team #<slug> per un team. Se l’account non ha un nome, mostra l’indirizzo email, poi l’ID utente. Un problema senza assegnatario mostra unassigned.

Referenti, cronologia e inbox

logbrew issues owners "<issue_id>" --json
logbrew issues ownership --project "<project_id>" --json
logbrew issues ownership set --project "<project_id>" \
  --rules ownership.txt --codeowners .github/CODEOWNERS --json
logbrew issues activity "<issue_id>" --limit 50 --json
logbrew inbox --json
logbrew inbox read --json

issues owners elenca i referenti suggeriti e le prove che ha controllato. issues ownership set invia file locali di massimo 128 KiB ciascuno. Un file vuoto cancella il testo corrispondente. issues activity e inbox accettano --limit da 1 a 200, e --cursor-time con --cursor-id presi da next_cursor. Consulta Trova il referente di un problema.

Imposta le regole di gravità

logbrew issues rule "<issue_id>" warning --json
logbrew logs rule "<log_id>" info --ignore --json

La gravità vale info, warning, error, critical o source. source mostra di nuovo la gravità acquisita. --ignore nasconde i log corrispondenti dall’elenco predefinito dei log. Senza --ignore, la regola li mostra.

Leggi la pagina successiva

Log, problemi, azioni, metriche e tracce accettano la paginazione con cursore. Le release no. Usa --pagination cursor per la prima pagina:

logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 --json

La risposta contiene logs e next_cursor. Un next_cursor non nullo contiene time e id. Inviali con --cursor-time e --cursor-id:

logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 \
  --cursor-time "<returned_time>" \
  --cursor-id "<returned_id>" --json

Mantieni gli stessi filtri e lo stesso limite in ogni pagina. Fermati quando next_cursor è null. Per capire se esistono altre pagine usa il cursore, non il numero di righe. L’ultima pagina può essere vuota:

{
  "logs": [],
  "next_cursor": null
}

Problemi, azioni e metriche usano la stessa forma, con issues, actions o metrics al posto di logs.

Monitoraggio in tempo reale

logbrew watch --json trasmette in tempo reale log, problemi e azioni. Aggiungi logs, issues o actions per trasmettere un solo tipo. tail, follow e stream sono alias di watch. Watch non supporta tracce o span. Watch richiede --json. Senza questo flag, il comando scrive watch streams JSON for agents ed esce con codice 1. Negli eventi dei problemi di watch, un problema archiviato compare come ignored, senza priorità. Leggi il problema per ottenerne lo stato e la priorità attuali. Watch accetta solo --severity, come --severity error,critical. logbrew watch actions non accetta --severity. La CLI applica questo filtro dopo aver ricevuto gli eventi. Non riduce ciò che il server invia. Watch non ha filtri di progetto, release, ambiente o tempo. Per questi filtri, usa un comando read. Dopo una disconnessione temporanea, la CLI attende e poi si riconnette.

Leggi risultati ed errori

Inserisci --json prima o dopo il comando. Leggi il codice di uscita prima di usare l’output. Non analizzare l’output leggibile dalle persone: può cambiare tra una versione e l’altra.

Codice di uscita	Significato
`0`	Operazione riuscita. Il JSON è sull’output standard.
`1`	Il comando non è riuscito durante l’esecuzione, per esempio per un errore dell’API o di rete.
`2`	La CLI ha rifiutato il comando prima di eseguirlo.

L’output di successo mantiene la forma della risposta dell’API. Può essere un array o un oggetto. Senza paginazione con cursore, una lettura dei log restituisce un array. Un array vuoto significa che nessun log corrisponde. Non è un errore. Gli errori vanno sull’errore standard. L’eccezione è debug-artifacts --json, che scrive gli errori sull’output standard. Un errore JSON contiene ok, error, message e next. Usa error come codice di errore stabile. Esamina next prima di eseguire il comando che suggerisce. Per esempio, logbrew watch traces --json esce con codice 2 e scrive:

{
  "ok": false,
  "error": "unknown_resource",
  "message": "unknown resource: traces",
  "next": "use logbrew traces for recent traces, or logbrew trace <trace_id> for one trace"
}

logbrew read logs --limit 0 --json esce con codice 2 e scrive:

{
  "ok": false,
  "error": "invalid_limit",
  "message": "invalid limit: 0",
  "next": "use --limit with a positive whole number"
}

Correggi il valore ed esegui di nuovo il comando. Un comando rifiutato non è un risultato vuoto. Consulta Errori API per gli errori HTTP e il riferimento dell’API di telemetria per le richieste dirette all’API.

​Come funziona la CLI

​Leggi il report di diagnostica di un progetto

​Esempio: accesso all’account mancante

​Filtri

​Seleziona un’occorrenza del problema

​Cambia stato e priorità dei problemi

​Assegna i problemi

​Referenti, cronologia e inbox

​Imposta le regole di gravità

​Leggi la pagina successiva

​Monitoraggio in tempo reale

​Leggi risultati ed errori