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

Compares running config against saved config by default,
or against a specific revision number. Useful for previewing
changes before committing or reviewing what has drifted.

Args:
    rev: Optional revision number to compare against

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"

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 error means the
commands contain invalid syntax or paths.

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.

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.

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"