kuma-tools

CLI per aggiungere e gestire monitor su Uptime Kuma.

Requisiti

• Node.js ≥ 22
• Uptime Kuma v2.x (comunicazione via Socket.IO)

Setup

npm install
npm link        # rende disponibile il comando `kuma` globalmente
kuma configure  # recupera le credenziali da Passwd Manager e le salva in ~/.kuma-tools

Le credenziali vengono salvate in ~/.kuma-tools (chmod 600) e caricate automaticamente ad ogni comando. Non serve nessun .env.

Alternativa manuale (senza Passwd Manager)

Crea ~/.kuma-tools a mano:

KUMA_URL="https://your-kuma-instance.com"
KUMA_USERNAME="your_username"
KUMA_PASSWORD="your_password"

chmod 600 ~/.kuma-tools

Comandi

kuma configure

Recupera le credenziali Kuma (URL, username, password) dal Passwd Manager e le salva in ~/.kuma-tools. Va eseguito una volta sola al primo setup, o quando le credenziali cambiano.

kuma configure

Le credenziali vengono lette dall'env trellis tramite il .secret-fetcher presente nella directory del progetto.

kuma add [url] [name]

Aggiunge un singolo monitor. Il nome viene ricavato automaticamente dall'URL (es. https://example.com → example) e mostrato pre-compilato — premi Invio per tenerlo o scrivi sopra per cambiarlo. Legge automaticamente il .secret-fetcher dalla directory corrente per assegnare il gruppo e l'etichetta. Se il gruppo non esiste in Kuma viene creato automaticamente.

kuma add https://miosito.it                    # nome pre-compilato: "miosito"
kuma add https://miosito.it "Mio Sito"         # nome passato direttamente
kuma add https://miosito.it --interval 1800

Modalità Trellis: dentro una cartella di progetto Trellis basta scrivere kuma add senza argomenti — fa tutto da solo. Rileva automaticamente nome e URL da .env.example e dai file wordpress_sites.yml, mostra i valori pre-compilati e chiede solo di scegliere l'ambiente (produzione, staging o entrambi). Premi Invio per confermare. L'ambiente viene indicato tramite etichette colorate — 🔴 production e 🟠 staging — senza aggiunte al nome del monitor.

cd /path/al/progetto-trellis
kuma add
# → rileva: nome "mio-progetto", URL produzione e staging
# → selezione ambiente → conferma con Invio
# → monitor creato con etichetta production (rossa) o staging (arancione)

Default applicati automaticamente:

| Parametro | Default | |----------------------------------|--------------| | Intervallo check | 3600s | | Tentativi prima di down | 2 | | Intervallo tra tentativi | 300s | | Timeout richiesta | 48s | | Reinvia notifica dopo N down | 1 | | Notifica scadenza SSL | attiva | | Notifica scadenza dominio | attiva | | Cache buster | attivo | | Reindirizzamenti massimi | 10 | | Codici di stato accettati | 200-299 | | Notifiche | attive |

Opzioni:

--interval <seconds>        Intervallo check, min 20 (default: 3600)
--retry-interval <seconds>  Intervallo tra tentativi, min 20 (default: 300)
--retries <n>               Tentativi prima di down, 0-10 (default: 2)
--timeout <seconds>         Timeout richiesta, 1-300 (default: 48)
--resend <n>                Reinvia notifica dopo N down consecutivi (default: 1)
--max-redirects <n>         Reindirizzamenti massimi (default: 10)
--status-codes <codes>      Codici accettati (default: 200-299)
--no-cert-expiry            Disabilita notifica scadenza SSL
--no-cache-buster           Non aggiungere il cache buster
--group                     Seleziona il gruppo o nessuno in modo interattivo (ignora .secret-fetcher)
--group-id <id>             Usa un ID gruppo specifico direttamente (ignora .secret-fetcher)
--secret-path <path>        Cartella dove cercare il .secret-fetcher (default: cartella corrente)

kuma setup [name] [url]

Wizard interattivo che crea un monitor e lo collega a una pagina di stato in un solo flusso guidato.

kuma setup                                   # tutto interattivo
kuma setup "Nome Sito" https://example.com   # nome e URL già noti, resto interattivo
kuma setup --settings                        # mostra anche i parametri avanzati da modificare

Flusso:

1. Chiede nome e URL se non forniti
2. Con --settings: mostra ogni parametro con il default precompilato — premi Invio per tenerlo, scrivi sopra per cambiarlo
3. Gruppo: se esiste un .secret-fetcher lo assegna automaticamente (creando il gruppo se non esiste), altrimenti chiede Sì / No
4. Crea il monitor
5. Vuoi aggiungerlo a una status page? Sì, esistente / Sì, nuova / No
   • Esistente → select interattivo delle pagine (con opzione Annulla che riporta alla domanda)
   • Nuova → chiede titolo (default: nome del monitor) e slug (default: generato dal titolo)

Opzioni:

--settings                  Mostra i parametri avanzati da modificare prima di creare il monitor
--interval <seconds>        Intervallo check, min 20 (default: 3600)
--retry-interval <seconds>  Intervallo tra tentativi, min 20 (default: 300)
--retries <n>               Tentativi prima di down, 0-10 (default: 2)
--timeout <seconds>         Timeout richiesta, 1-300 (default: 48)
--resend <n>                Reinvia notifica dopo N down consecutivi (default: 1)
--max-redirects <n>         Reindirizzamenti massimi (default: 10)
--status-codes <codes>      Codici accettati (default: 200-299)
--no-cert-expiry            Disabilita notifica scadenza SSL
--no-cache-buster           Non aggiungere il cache buster
--secret-path <path>        Cartella dove cercare il .secret-fetcher (default: cartella corrente)

Con --settings vengono mostrati tutti i parametri con il valore di default già precompilato. Premi Invio per tenerlo, scrivi sopra per cambiarlo:

Impostazioni avanzate — premi Invio per mantenere il default:

Intervallo check (secondi): 3600
Intervallo tra tentativi (secondi): 300
Tentativi prima di down (0-10): 2
Timeout richiesta (secondi, 1-300): 48
Reinvia notifica dopo N down consecutivi: 1
Reindirizzamenti massimi: 10
Codici di stato accettati: 200-299
Notifica scadenza SSL: Attiva / Disattiva
Cache buster: Attivo / Disattivo

kuma edit

Modifica un monitor esistente. Mostra i valori attuali precompilati — premi Invio per tenerli, scrivi sopra per cambiarli.

kuma edit       # selezione interattiva del monitor da modificare
kuma edit 42    # modifica direttamente per ID

Campi modificabili: nome, URL, intervallo check, intervallo tra tentativi, tentativi prima di down, timeout, reinvio notifica, codici di stato, notifica SSL, cache buster, gruppo di appartenenza.

Per il gruppo puoi scegliere: mantenere quello attuale, cambiarlo, oppure rimuoverlo dal gruppo.

Propagazione tag: se il gruppo cambia, i tag del monitor vengono applicati al nuovo gruppo e rimossi dal vecchio se nessun altro monitor li usa ancora.

kuma move

Sposta un monitor in un altro gruppo in modo rapido, senza dover modificare tutti gli altri campi.

kuma move       # selezione interattiva del monitor e del gruppo
kuma move 42    # sceglie solo il gruppo per il monitor id=42

Nella lista monitor viene mostrato il gruppo attuale in grigio a fianco. Nella lista gruppi il gruppo attuale è marcato con ← attuale. Se selezioni lo stesso gruppo corrente, esce senza fare nulla.

Propagazione tag: i tag del monitor vengono applicati automaticamente al gruppo di destinazione. Se il gruppo di origine non ha altri monitor con quegli stessi tag, i tag vengono rimossi anche da lui.

kuma import <file>

Importa una lista di siti da file .json o .csv. Applica gli stessi default di add.

kuma import sites.json
kuma import sites.csv --dry-run
kuma import sites.json --interval 1800 --group-id 5
kuma import sites.json --group          # selezione interattiva del gruppo (o nessuno)

Formato JSON:

[
  { "name": "esempio", "url": "https://example.com" },
  { "name": "Mio Sito",  "url": "https://miosito.it", "interval": 1800 }
]

Formato CSV:

name,url,interval
esempio,https://example.com,3600
Mio Sito,https://miosito.it,1800

Opzioni:

--interval <seconds>        Sovrascrive intervallo check per tutti (min 20)
--retry-interval <seconds>  Sovrascrive intervallo tra tentativi per tutti (min 20)
--retries <n>               Sovrascrive tentativi per tutti (0-10)
--timeout <seconds>         Sovrascrive timeout per tutti (1-300)
--group                     Seleziona il gruppo o nessuno in modo interattivo (ignora .secret-fetcher)
--group-id <id>             Forza ID gruppo per tutti (ignora .secret-fetcher)
--secret-path <path>        Directory alternativa per .secret-fetcher
--dry-run                   Mostra cosa verrebbe aggiunto senza contattare Kuma

Se --group-id o --group non vengono usati, il gruppo viene rilevato automaticamente dal .secret-fetcher (come per kuma add). Se non esiste, viene creato. Se usi --group-id con un ID non valido, vedrai il messaggio: "ID gruppo non valido — usa 'kuma groups' per vedere gli ID disponibili".

kuma list

Elenca tutti i monitor raggruppati sotto il loro gruppo, con rami ├─ / └─. I monitor senza gruppo appaiono in fondo sotto (senza gruppo).

kuma list
kuma list --live    # mostra stato reale su/giù
kuma list --json    # output JSON grezzo

Esempio di output:

clienti  • attivo
  ├─ Sito A                        https://sitoa.it                 ✓ su
  └─ Sito B                        https://sitob.it                 ✗ giù

(senza gruppo)
  └─ Test                          https://example.com              • attivo

Totale: 3 monitor, 1 gruppi  (usa --live per stato reale su/giù)

kuma groups

Elenca solo i gruppi monitor con il loro ID. Utile per trovare l'ID da passare a --group-id quando vuoi aggiungere un monitor a un gruppo specifico.

kuma groups
kuma groups --json

Esempio di output:

ID     Nome                                     Stato
───────────────────────────────────────────────────────
5      Clienti                                  • attivo
8      Interni                                  • attivo
12     Progetto X                               ⏸ pausa

Per aggiungere un monitor a un gruppo specifico, sostituisci <id> con l'ID reale:

kuma add https://sito.it "Nome sito" --group-id <id>

kuma delete

Elimina un monitor. La conferma usa una selezione Sì/No — di default è impostata su No per evitare eliminazioni accidentali.

Propagazione tag: se il monitor era l'unico nel suo gruppo con un certo tag, quel tag viene rimosso anche dal gruppo.

kuma delete        # selezione interattiva del monitor da eliminare
kuma delete 42     # elimina direttamente per ID
kuma delete 42 -y  # salta la conferma

kuma pause / kuma resume

Mette in pausa o riattiva un monitor senza eliminarlo. pause mostra solo i monitor attivi, resume solo quelli in pausa.

kuma pause        # selezione interattiva (solo monitor attivi)
kuma pause 42     # mette in pausa direttamente per ID

kuma resume       # selezione interattiva (solo monitor in pausa)
kuma resume 42    # riattiva direttamente per ID

kuma resume riattiva automaticamente anche il gruppo padre se è in pausa, altrimenti il monitor resterebbe invisibile nella UI.

kuma status-page add <title> <slug>

Crea una nuova pagina di stato pubblica con i monitor già inclusi.

# selezione interattiva dei monitor (checkbox)
kuma status-page add "Nome che vuoi dare" "slug-unico"

# oppure passa gli ID direttamente
kuma status-page add "Nome che vuoi dare" "slug-unico" --monitors <id1>,<id2>

Nella selezione interattiva è sempre presente la voce ↩ Annulla ed esci come prima opzione per uscire senza creare nulla.

Opzioni:

--monitors <ids>      ID monitor separati da virgola (se omesso: selezione interattiva)
--group-name <name>   Nome del gruppo nella pagina (default: "Monitor")

La pagina sarà accessibile su: https://tuo-kuma/status/slug-unico

Lo slug accetta solo lettere minuscole, numeri e trattini (es. miei-siti).

kuma status-page edit

Modifica i monitor di una pagina di stato esistente. Mostra tutti i monitor disponibili con quelli già presenti nella pagina pre-selezionati e marcati con già incluso in verde. È sempre presente la voce ↩ Annulla ed esci per uscire senza salvare. Per svuotare la pagina, deseleziona tutti i monitor e conferma.

kuma status-page edit             # selezione interattiva della pagina
kuma status-page edit "slug"      # modifica direttamente per slug

kuma status-page list

Elenca tutte le pagine di stato con slug e URL.

kuma status-page list

kuma status-page delete

Elimina una pagina di stato. La conferma usa una selezione Sì/No — di default è impostata su No.

kuma status-page delete                          # selezione interattiva
kuma status-page delete "slug-da-eliminare"      # elimina direttamente per slug
kuma status-page delete "slug-da-eliminare" -y   # salta la conferma

Integrazione con .secret-fetcher

Se nella directory corrente è presente un file .secret-fetcher con un groupKey:

groupKey="nome-progetto"

kuma add, kuma import e kuma setup fanno automaticamente:

1. Cercano in Kuma un gruppo monitor con nome "nome-progetto" → lo usano come parent. Se non esiste, lo creano.
2. Trovano o creano un tag "nome-progetto" → lo applicano sia al gruppo che al singolo monitor appena creato

Per usare .secret-fetcher da un'altra directory:

kuma add https://url.com "Nome" --secret-path /path/al/progetto

Per ignorare il .secret-fetcher e forzare un gruppo manuale:

kuma add https://url.com "Nome" --group-id 5

Integrazione con trellis-tools

kuma-tools è disponibile anche come sottocomando di trellis-tools. Se usi già trellis-tools nel progetto, non serve installare kuma-tools separatamente — tutti i comandi sono accessibili sotto trellis-tools kuma:

npx trellis-tools kuma add
npx trellis-tools kuma list
npx trellis-tools kuma configure
# ecc.

Al termine del comando trellis-tools server setup, viene chiesto automaticamente se aggiungere il sito su Uptime Kuma.