Guía de la CLI

La CLI viene en ambas ediciones (escritorio y server). Todos los comandos funcionan sin sudo una vez instalado el servicio.

Ejemplo de CLI — los servidores de los últimos 5 minutos (al terminar, vuelve al prompt):

Ejemplo de la CLI de CaudalGhost: la salida de «caudalghost hosts 5m» es una tabla de servidores remotos con bytes recibidos, enviados y total; al terminar, el shell vuelve al prompt.

Rangos de tiempo

Varios subcomandos aceptan un rango como argumento. Los valores válidos son:

Rango	Significado
`5m`, `1h`, `24h`, `7d`, `30d`, `90d`, `365d`	Ventana relativa hacia atrás desde ahora
`hoy`	Desde medianoche hasta ahora
`ayer`	El día natural anterior completo
`este-mes`	Desde el día 1 del mes actual hasta ahora
`este-anio`	Desde el 1 de enero del año actual hasta ahora
`dia:AAAA-MM-DD`	Un día natural concreto, p. ej. `dia:2026-06-30`
`rango:AAAA-MM-DD:AAAA-MM-DD`	Un intervalo de días concreto, p. ej. `rango:2026-06-01:2026-06-30`

Un rango mal escrito (fecha inválida, intervalo al revés…) termina el comando con el código de salida 5.

`caudalghost ping`

Comprueba que la CLI puede hablar con el daemon por el socket Unix. Útil en scripts antes de pedir datos.

caudalghost ping

`caudalghost now`

Tráfico ahora mismo, por interfaz (tasas por segundo).

caudalghost now

Con --seconds controlas la ventana de muestreo instantáneo (por defecto, un puñado de segundos):

caudalghost now --seconds 5

`caudalghost total`

Totales acumulados por interfaz para un rango.

caudalghost total 24h

interfaz    rx        tx        total
wlan0       842 MiB   119 MiB   961 MiB
eth0        12 MiB    3 MiB     15 MiB
Σ total     854 MiB   122 MiB   976 MiB

`caudalghost top`

Top de aplicaciones por consumo de red, para un rango o para una ventana instantánea.

caudalghost top 24h

app           rx        tx        total
firefox       612 MiB   88 MiB    700 MiB
thunderbird   140 MiB   21 MiB    161 MiB
syncthing     45 MiB    39 MiB    84 MiB
Σ total       797 MiB   148 MiB   945 MiB

También acepta una ventana instantánea con --seconds, en vez de un rango:

caudalghost top --seconds 10

La fila (otros) no aparece en top: cada app se lista con su propio nombre.

`caudalghost hosts`

Servidores remotos (por hostname), agrupados por dominio raíz, para un rango.

caudalghost hosts 5m

host                rx        tx        total
cdn.ejemplo.net      38 MiB    2 MiB     40 MiB
api.ejemplo.org      9 MiB     4 MiB     13 MiB
(otros)              3 MiB     1 MiB     4 MiB
Σ total              50 MiB    7 MiB     57 MiB

A diferencia de top, aquí sí puede aparecer una fila (otros): agrupa los hosts que no entran en el top registrado por app.

Puedes acotar a una sola aplicación con --app:

caudalghost hosts 24h --app firefox

`caudalghost serie`

Evolución del caudal total a lo largo de un rango, en cubos de tiempo (sparkline en la terminal + tabla).

caudalghost serie 24h

El tamaño del cubo se controla con --bucket (minute, hour o day):

caudalghost serie 7d --bucket hour

`caudalghost live`

Panel interactivo en la terminal (TUI): apps, interfaces y hosts, en vivo o sobre un rango histórico, con detalle por app→hosts, selector de rango y resaltado por umbral.

caudalghost live

Panel en vivo de CaudalGhost en la terminal (TUI): tres bandas con los gráficos de descarga y subida, las apps e interfaces en vivo, y el histórico acumulado.

Dentro de live puedes moverte entre apps, interfaces y hosts, entrar en una app para ver qué hosts consumen su tráfico, cambiar de rango sin salir del panel, y marcar visualmente los consumos que superan un umbral. Sales con la tecla indicada en el propio panel.

Flags de salida

Estos flags funcionan en ping, now, total, top, hosts y serie (no en live, que es un panel interactivo aparte):

Flag	Efecto
`-o, --output table\|json\|csv\|ndjson`	Formato de salida. Por defecto, `table`
`--json`	Atajo de `-o json`
`-u, --units binary\|decimal\|bits`	Unidades: binarias (KiB, MiB…), decimales (KB, MB…) o bits (Kbps, Mbps…)
`-n, --limit N`	Limita el número de filas
`--sort <col>`	Ordena por una columna (p. ej. `--sort total`)
`-r, --reverse`	Invierte el orden
`--fields a,b,c`	Proyecta solo esas columnas — solo en `csv`, `json` y `ndjson`
`--no-header`	Omite la cabecera — solo en `csv`
`--watch`	Refresca la tabla cada cierto intervalo — solo con `-o table`
`--interval SECS`	Intervalo de refresco para `--watch`
`--quiet`	Silencia mensajes que no sean el resultado
`--no-color`	Desactiva color (también respeta la variable `NO_COLOR`)

Las columnas de las tablas van en minúsculas: app, host o interfaz según el comando, más rx, tx y total, con una fila final Σ total.

Ejemplo en JSON (incluye "schema":1 para que puedas versionar tu parseo):

caudalghost top 24h -o json

{"schema":1,"rango":"24h","filas":[
  {"app":"firefox","rx":641925120,"tx":92274688,"total":734199808},
  {"app":"thunderbird","rx":146800640,"tx":22020096,"total":168820736}
],"total":{"rx":835055616,"tx":155189248,"total":990244864}}

Ejemplo en CSV con proyección de columnas:

caudalghost hosts 24h --fields host,total -o csv

host,total
cdn.ejemplo.net,41943040
api.ejemplo.org,13631488

Conectar a un daemon en otra ruta

Si corres un daemon manual con un socket distinto (avanzado), pásalo con --socket o con la variable de entorno CAUDALGHOST_SOCKET:

caudalghost live --socket /run/caudalghost/caudalghost.sock

export CAUDALGHOST_SOCKET=/run/caudalghost/caudalghost.sock
caudalghost now

En la instalación estándar no hace falta: la CLI autodetecta el socket del servicio.

Códigos de salida

Código	Significado
`0`	OK
`1`	Otro error
`2`	Uso inválido (flags o argumentos mal formados)
`3`	Daemon inalcanzable
`4`	Error de negocio (p. ej. app o host inexistente)
`5`	Rango de tiempo inválido

Completado de shell y man page

El paquete instala completado de comandos para bash, zsh y fish, además de una página de manual:

man caudalghost

Versión instalada

caudalghost --version

Muestra la versión, el hash de git y la fecha de compilación — útil para reportar en qué build estás cuando pidas ayuda.