Neighbor state, uptime, and prefixes received per peer across all
address families. Most useful on routers running BGP; if BGP is not
running, the router returns an error response ("success": false).

Returns a unified diff of revision rev+1 -> rev, i.e. what that
commit changed. Defaults to the most recent commit (rev 0). Revision
numbers are the `revision` values listed by vyos_config_history.

Note: the VyOS HTTP API cannot compare the running config against
the saved config, so this tool only diffs committed revisions.

Args:
    rev: Commit revision number (omit or 0 = most recent)

Returns the numbered config revisions VyOS retains, newest first,
each with its timestamp, the user who committed it, the method
(e.g. cli, vyos-http-api), and an optional comment. Pair with
vyos_config_diff(rev) to inspect what changed in a given revision.

Note: VyOS exposes no rollback endpoint over the HTTP API, so this
server can report revision history but cannot revert to a revision.

Every operation in `commands` is applied in a single commit-confirm
window — the whole batch commits or rolls back together, never
partially. Prefer batching all related set/delete changes into one
call rather than making several sequential calls; this is faster and
keeps related changes atomic.

This is the safe default — changes auto-revert after 5 minutes unless
confirmed with vyos_confirm. Confirm or let a pending window expire
before calling again: a call while one is pending commits WITHOUT its
own rollback and raises. An error saying changes were COMMITTED means
they are live; do not retry blindly. A `warning` key in the result
means auto-rollback could not be verified (`service https` changes).

Args:
    commands: List of config operations, each with 'op'
        ('set'/'delete') and 'path' (list of strings). Pass as many
        as belong together. Example:
        [{"op": "set", "path": ["firewall", "group",
          "network-group", "MY_GROUP", "network", "10.0.0.0/8"]},
         {"op": "set", "path": ["firewall", "group",
          "network-group", "MY_GROUP", "network", "192.168.0.0/16"]}]

Fetches the raw RST content from the VyOS docs repository.
Use vyos_docs_search to find the path for a topic.

Args:
    path: Doc path, e.g. "docs/configuration/firewall/groups.rst"

Ranks matching doc pages by how many query terms appear in the path
and body. Each result is a dict with 'path', 'title', and 'snippet'
(a context excerpt when the query matches the page body, else None).
Use vyos_docs_read to fetch the full content of a result.

Args:
    query: Search terms, e.g. "firewall group" or "nat hairpin"
    max_results: Maximum number of results to return (default 10).
        Capped internally at ~30 (only fetched pages can rank).

Returns true/false in the data field.

Args:
    path: Configuration path to check,
        e.g. ["service", "https", "api"]

Returns a dict keyed by 'firewall', 'nat_source', and
'nat_destination', each holding the corresponding `show` output. On
partial failure the affected key holds an error dict with
"success": false and "error" set — check "success" before using
"data"; the commands that succeeded are still returned. Most useful
on routers with complex rulesets.

Args:
    path: Command path, e.g. ["pki", "wireguard", "key-pair"]

Downloads and installs a new system image. This does not
reboot — the new image will be used on next boot.

The call blocks until the router finishes downloading and installing,
which can take several minutes for a full ISO (it waits up to 30
minutes). On a timeout error the install may still be running: check
vyos_show(["system", "image"]) before retrying.

Args:
    url: URL to the VyOS ISO image

WARNING: Cannot delete the currently running image.

Args:
    name: Image name, e.g. "1.4-rolling-202102280559"

With no argument, returns the summary table for all interfaces.
Pass an interface spec as path elements (e.g. ["ethernet", "eth0"])
to get detailed byte/packet/error counters for a single interface.

Args:
    interface: Optional interface path elements, e.g. ["ethernet", "eth0"]

Args:
    file: Path to config file on the router,
        e.g. "/config/test.config"

Provide either a file path on the router or an inline
config string (VyOS curly-brace format).

Args:
    file: Path to config file on the router
    string: Inline config in VyOS format, e.g.
        'interfaces { ethernet eth1 { description "test" } }'

Returns the API response with the ping output (per-reply RTTs and a
loss/latency summary) in its data field. If no reply arrives the
router reports failure, so the tool errors with the ping output.
Requires VyOS rolling 2026.08.18 or later; older routers lack the
/ping endpoint and this tool reports so.

Args:
    host: Destination hostname or IP, e.g. "8.8.8.8"
    count: Number of echo requests, 1-10 (default 5)
    vrf: Optional VRF to ping from

WARNING: This will shut down the router. The router will
need physical or out-of-band access to power back on.

WARNING: This will reboot the router. All active sessions
and traffic will be interrupted.

Args:
    path: Command path, e.g. ["ip", "bgp", "192.0.2.11"]

Args:
    path: Configuration path as list of strings, e.g. ["firewall", "group"]

Use this instead of vyos_retrieve when a node has multiple
values (e.g. addresses on an interface).

Args:
    path: Configuration path, e.g.
        ["interfaces", "dummy", "dum0", "address"]

Raises ValueError (propagated to the caller) if family or protocol is
not one of the documented values.

Args:
    family: Address family — "ip" (IPv4, default) or "ipv6".
    protocol: Optional source filter — one of bgp, ospf, ospfv3,
        static, connected, kernel, rip, isis. Omit for all routes.

Args:
    path: Command path as list of strings, e.g. ["interfaces", "ethernet"]

Returns a dict keyed by resource (cpu, memory, storage, uptime),
each holding the corresponding `show system ...` output. Handy for
a quick health snapshot of the router.

Returns the API response with an mtr report (per-hop loss and
latency) in its data field. Useful for diagnosing reachability and
path issues from the router's perspective. The host must be a valid
hostname or IP address.

Args:
    host: Destination hostname or IP, e.g. "8.8.8.8"
    vrf: Optional VRF to trace from. Needs VyOS rolling 2026-08-24 or
        later; older routers silently ignore it and use the default VRF.

Applies commands with a 1-minute commit-confirm window and does NOT
confirm, so the router automatically rolls back. This is not a true
dry-run — the configuration is temporarily applied for up to 1 minute.

A successful response means the syntax is valid. An HTTP error means the
commands contain invalid syntax or paths — unless it says the changes were
COMMITTED, in which case they persist and must be reviewed.

Args:
    commands: List of config operations, each with 'op'
        ('set'/'delete') and 'path' (list of strings).
        Example: [{"op": "set", "path": ["firewall",
        "group", "network-group", "MY_GROUP"]}]