diff --git a/content/docs/tools/cli.md b/content/docs/tools/cli.md index b53d6fb..dc9dba5 100644 --- a/content/docs/tools/cli.md +++ b/content/docs/tools/cli.md @@ -4,7 +4,7 @@ weight: 1 prev: /docs/tools/ --- -The **nxthdr** CLI is a command line tool to interact with the nxthdr platform. It supports authentication, peering operations, and probing credits management. +The **nxthdr** CLI is a command line tool to interact with the nxthdr platform. It supports authentication, peering, and probing operations. Source code: [github.com/nxthdr/cli](https://github.com/nxthdr/cli) @@ -59,10 +59,105 @@ Displays your daily probing credits usage. Each probe you send consumes one cred Example output: ``` -Probing credits (today): - Used: 1500 - Limit: 10000 - Remaining: 8500 +credits +─────── +used 0 +limit 1000000 +remaining 1000000 +``` + +### Agents + +```bash +nxthdr probing agents +``` + +Lists available probing agents and their source prefixes. + +Example output: + +``` +id status prefixes +───────────────────────────────────────────────────────────────────────────── +vltewr01 healthy 2a0e:97c0:8a0::/48 (anycast), 2a0e:97c0:8a3::/48 (unicast) +vltsgp01 healthy 2a0e:97c0:8a0::/48 (anycast), 2a0e:97c0:8a5::/48 (unicast) +vltcdg01 healthy 2a0e:97c0:8a0::/48 (anycast), 2a0e:97c0:8a4::/48 (unicast) +``` + +### Send + +```bash +nxthdr probing send --agent [file] +``` + +Sends probes from the given agent. Each probe is one line in the format `dst_addr,src_port,dst_port,ttl,protocol` (protocol is `icmpv6` or `udp`). Reads from a file or stdin if no file argument is given. Use `--agent` multiple times for multi-agent sends. + +```bash +echo '2001:4860:4860::8888,24000,33434,16,udp' | nxthdr probing send --agent vltcdg01 +``` + +Example output: + +``` +✓ measurement submitted +id d80d7ecf-d60b-42af-bd22-2f9937e44a7f +probes 1 × 1 agent +vltcdg01 2a0e:97c0:8a0:1865:ceb8:372d:d58:fe47 + +→ nxthdr probing measurement-status d80d7ecf-d60b-42af-bd22-2f9937e44a7f +→ nxthdr probing results --src-ip 2a0e:97c0:8a0:1865:ceb8:372d:d58:fe47 +``` + +The output includes the measurement ID and the source IP used by each agent — both needed to retrieve results. + +### Measurement status + +```bash +nxthdr probing measurement-status +``` + +Shows the progress of a measurement by ID. + +Example output: + +``` +measurement +─────────── +id d80d7ecf-d60b-42af-bd22-2f9937e44a7f +status complete +agents 1/1 complete +probes 1/1 sent +agent probes sent/expected complete +──────────────────────────────────────── +vltcdg01 1/1 yes +``` + +### Results + +```bash +nxthdr probing results --src-ip [--since ] [--until ] +``` + +Queries probe replies from ClickHouse. `--src-ip` is the source IP returned by `send`. + +```bash +nxthdr probing results \ + --src-ip 2a0e:97c0:8a0:1865:ceb8:372d:d58:fe47 \ + --since "2026-06-16 00:00:00" +``` + +Example output: + +``` +agent src dst ttl reply rtt +──────────────────────────────────────────────────────────────────────────────────────────────────────── +vltcdg01 2a0e:97c0:8a0:1865:ceb8:372d:d58:fe47 2001:4860:4860::8888 16 2001:4860:4860::8888 0.00ms +``` + +Use `--output json` for machine-readable output suitable for piping or scripting: + +```bash +nxthdr probing results --src-ip --since "..." --output json ``` ## Peering