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"]

Returns true/false in the data field.

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

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.

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

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.

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

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"]

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.

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.

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.

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).

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"]}]

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"]}]

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

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

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" } }'

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

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

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"

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).

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"