rauto - Network Device Automation CLI

中文文档

rauto is a powerful CLI tool for network device automation, written in Rust. It leverages the rneter library for intelligent SSH connection management and utilizes minijinja for flexible command templating.

Features

• Double Template System: Command Templates (Jinja2) & Device Profiles (TOML).
• Intelligent Connection Handling: Uses rneter for SSH state management.
• Dry Run Support: Preview commands before execution.
• Variable Injection: Load variables from JSON.
• Extensible: Custom TOML device profiles.
• Built-in Web Console: Start browser UI with rauto web.
• Embedded Web Assets: Frontend files are embedded into the binary for release usage.
• Saved Connection Profiles: Reuse named connection settings across commands.
• Session Recording & Replay: Record SSH sessions to JSONL and replay offline.

Installation

From Binary (Recommended)

Download the latest release for your platform from GitHub Releases.

From Crates.io

cargo install rauto

From Source

Ensure you have Rust and Cargo installed.

git clone https://github.com/demohiiiii/rauto.git
cd rauto
cargo build --release

The binary will be available at target/release/rauto.

Usage

1. Template Mode (Recommended)

Render commands from a template and execute them on a device.

Basic Usage:

rauto template show_version.j2 \
    --host 192.168.1.1 \
    --username admin \
    --password secret \
    --ssh-port 22

With Variables: Given a template templates/commands/configure_vlan.j2 and variables file templates/example_vars.json:

rauto template configure_vlan.j2 \
    --vars templates/example_vars.json \
    --host 192.168.1.1 \
    --username admin \
    --password secret \
    --ssh-port 22

Dry Run (Preview):

rauto template configure_vlan.j2 \
    --vars templates/example_vars.json \
    --dry-run

2. Direct Execution

Execute raw commands directly without templates.

rauto exec "show ip int br" \
    --host 192.168.1.1 \
    --username admin \
    --password secret \
    --ssh-port 22

Specifying Execution Mode: Execute a command in a specific mode (e.g., Enable, Config).

rauto exec "show bgp neighbor" \
    --host 192.168.1.1 \
    --username admin \
    --password secret \
    --ssh-port 22 \
    --mode Enable

3. Device Profiles

rauto supports built-in device profiles (inherited from rneter) and custom TOML profiles.

List Available Profiles:

rauto device list

Using a Specific Profile: Default is cisco. To use Huawei VRP:

rauto template show_ver.j2 \
    --host 192.168.1.1 \
    --username admin \
    --password secret \
    --ssh-port 22 \
    --device-profile huawei

Custom Device Profile: You can define custom profiles in templates/devices/*.toml.

Example templates/devices/custom_cisco.toml:

name = "custom_cisco"

[[prompts]]
state = "Enable"
patterns = ['^[^\s#]+#\s*$']

# ... see templates/devices/custom_cisco.toml for full example

Use it:

rauto exec "show ver" \
    --host 192.168.1.1 \
    --username admin \
    --password secret \
    --ssh-port 22 \
    --device-profile custom_cisco

Useful profile management commands:

rauto device list
rauto device show cisco
rauto device copy-builtin cisco my_cisco
rauto device delete-custom my_cisco
rauto device test-connection \
    --host 192.168.1.1 \
    --username admin \
    --password secret \
    --ssh-port 22

4. Web Console (Axum)

Start the built-in web service and open the visual console in your browser:

rauto web \
    --bind 127.0.0.1 \
    --port 3000 \
    --host 192.168.1.1 \
    --username admin \
    --password secret \
    --ssh-port 22

Then visit http://127.0.0.1:3000.

Web assets are embedded into the binary at build time.
For released binaries, users only need to run the executable (no extra static/ files required at runtime).

Web console key capabilities:

• Manage saved connections in UI: add, load, update, delete, and inspect details.
• Execute commands with saved connection info (load one connection, then run direct or template mode).
• Manage profiles (builtin/custom) and templates in dedicated tabs.
• Diagnose profile state machines in Prompt Management -> Diagnostics with visualized result fields.
• Switch Chinese/English in UI.
• Record execution sessions and replay recorded outputs in browser (list events or replay by command/mode).

5. Template Storage Commands

rauto templates list
rauto templates show show_version.j2
rauto templates delete show_version.j2

6. Saved Connection Profiles

You can save and reuse connection settings by name:

# Add/update a profile directly from CLI args
rauto device add-connection lab1 \
    --host 192.168.1.1 \
    --username admin \
    --ssh-port 22 \
    --device-profile cisco

# Reuse the saved profile
rauto exec "show version" --connection lab1

# Save current effective connection after a successful run
rauto device test-connection \
    --connection lab1 \
    --save-connection lab1_backup

# Manage saved profiles
rauto device list-connections
rauto device show-connection lab1
rauto device delete-connection lab1

Password behavior:

• --save-connection (used in exec/template/device test-connection) saves without password by default; add --save-password to include password fields.
• device add-connection saves password only when --password / --enable-password is explicitly provided.

7. CLI Quick Reference

Connection troubleshooting

rauto device test-connection \
    --host 192.168.1.1 \
    --username admin \
    --password secret \
    --ssh-port 22

Saved connection profiles

rauto device add-connection lab1 \
    --host 192.168.1.1 \
    --username admin \
    --ssh-port 22 \
    --device-profile cisco
rauto exec "show version" --connection lab1
rauto device list-connections

Profile management

rauto device list
rauto device show cisco
rauto device copy-builtin cisco my_cisco
rauto device show my_cisco
rauto device delete-custom my_cisco

Template storage management

rauto templates list
rauto templates show show_version.j2
rauto templates delete show_version.j2

Session recording & replay

# Record direct exec
rauto exec "show version" \
    --host 192.168.1.1 \
    --username admin \
    --password secret \
    --record-file ~/.rauto/records/show_version.jsonl \
    --record-level full

# Record template execution
rauto template show_version.j2 \
    --host 192.168.1.1 \
    --username admin \
    --password secret \
    --record-file ~/.rauto/records/template_run.jsonl \
    --record-level key-events-only

# Replay / inspect
rauto replay ~/.rauto/records/show_version.jsonl --list
rauto replay ~/.rauto/records/show_version.jsonl --command "show version" --mode Enable

Transaction blocks

# Tx block with inferred per-step rollback
rauto tx \
    --command "interface vlan 10" \
    --command "ip address 10.0.10.1 255.255.255.0" \
    --host 192.168.1.1 \
    --username admin \
    --password secret

# Tx block with explicit per-step rollback (repeatable flags)
rauto tx \
    --command "interface vlan 10" \
    --command "ip address 10.0.10.1 255.255.255.0" \
    --rollback-command "no interface vlan 10" \
    --rollback-command "no ip address 10.0.10.1 255.255.255.0" \
    --host 192.168.1.1 \
    --username admin \
    --password secret

# Tx block with per-step rollback from file (one per line, empty lines ignored)
rauto tx \
    --command "interface vlan 10" \
    --command "ip address 10.0.10.1 255.255.255.0" \
    --rollback-commands-file ./rollback.txt \
    --host 192.168.1.1 \
    --username admin \
    --password secret

# Tx block with per-step rollback from JSON array
rauto tx \
    --command "interface vlan 10" \
    --command "ip address 10.0.10.1 255.255.255.0" \
    --rollback-commands-json ./rollback.json \
    --host 192.168.1.1 \
    --username admin \
    --password secret

# Tx block with whole-resource rollback
rauto tx \
    --command "vlan 10" \
    --resource-rollback-command "no vlan 10" \
    --host 192.168.1.1 \
    --username admin \
    --password secret

Transaction workflow

# Execute a workflow from JSON
rauto tx-workflow ./workflow.json \
    --host 192.168.1.1 \
    --username admin \
    --password secret

# Dry-run: print workflow JSON and exit
rauto tx-workflow ./workflow.json --dry-run

Transaction workflow JSON example

{
  "name": "fw-policy-publish",
  "fail_fast": true,
  "blocks": [
    {
      "name": "addr-objects",
      "kind": "config",
      "fail_fast": true,
      "rollback_policy": "per_step",
      "steps": [
        {
          "mode": "Config",
          "command": "address-book global address WEB01 10.0.10.1/32",
          "timeout_secs": 10,
          "rollback_command": "delete address-book global address WEB01"
        }
      ]
    },
    {
      "name": "policy",
      "kind": "config",
      "fail_fast": true,
      "rollback_policy": {
        "whole_resource": {
          "mode": "Config",
          "undo_command": "delete security policies from-zone trust to-zone untrust policy allow-web",
          "timeout_secs": 10
        }
      },
      "steps": [
        {
          "mode": "Config",
          "command": "set security policies from-zone trust to-zone untrust policy allow-web match source-address WEB01",
          "timeout_secs": 10,
          "rollback_command": null
        }
      ]
    }
  ]
}

CLI ⇄ Web UI mapping

Operations (Web)                 CLI
-------------------------------- ---------------------------------------------
Direct Execute                   rauto exec
Template Render + Execute        rauto template
Transaction Block (Tx Block)     rauto tx
Transaction Workflow (Tx Flow)   rauto tx-workflow

Prompt Profiles (Web)            CLI
-------------------------------- ---------------------------------------------
Built-in profiles                rauto device list / rauto device show <name>
Copy builtin to custom           rauto device copy-builtin <builtin> <custom>
Custom profiles CRUD             rauto device show/delete <custom>

Template Manager (Web)           CLI
-------------------------------- ---------------------------------------------
List templates                   rauto templates list
Show template                    rauto templates show <name>
Delete template                  rauto templates delete <name>

Session Replay (Web)             CLI
-------------------------------- ---------------------------------------------
List records                     rauto replay <jsonl> --list
Replay command                   rauto replay <jsonl> --command "<cmd>" [--mode <Mode>]

Feature availability

Feature                                   Web UI   CLI
----------------------------------------- ------- ----
Connection profiles CRUD                 Yes     Yes
Execution history browser                Yes     Yes (by file)
Session recording (auto)                 Yes     Yes
Session replay list/inspect              Yes     Yes
Session replay UI table/detail           Yes     No
Prompt profile diagnose view             Yes     No
Workflow builder (visual)                Yes     No
Transaction workflow JSON execution      Yes     Yes

Migration tips (Web ⇄ CLI)

Workflow Builder → CLI
  1. In Web, open Tx Workflow step and click "Generate JSON".
  2. Download JSON (More Actions → Download JSON).
  3. Run: rauto tx-workflow ./workflow.json

Tx Block (custom per-step rollback) → CLI
  1. In Web, choose Rollback mode = "custom per-step".
  2. Use "text" to copy rollback lines.
  3. Run: rauto tx --rollback-commands-file ./rollback.txt ... (commands in same order)

CLI recordings → Web Replay
  1. Run with --record-file to create JSONL.
  2. Open Web → Session Replay, paste JSONL and inspect.

Start web console

rauto web \
    --bind 127.0.0.1 \
    --port 3000

Directory Structure

By default, rauto stores runtime data under ~/.rauto/.

Default directories:

• ~/.rauto/connections (saved connection profiles)
• ~/.rauto/profiles (custom device profiles)
• ~/.rauto/templates/commands
• ~/.rauto/templates/devices
• ~/.rauto/records (session recordings)

These folders are auto-created on startup.

For backward compatibility, local ./templates/ is still checked as a fallback.

~/.rauto
├── connections/            # Saved connection profiles (*.toml)
├── profiles/               # Custom profiles copied/created from builtin
├── templates/
│   ├── commands/           # Store your .j2 command templates here
│   └── devices/            # Store custom .toml device profiles here
└── records/                # Session recording output (*.jsonl)

You can specify a custom template directory using the --template-dir argument or RAUTO_TEMPLATE_DIR environment variable.

Configuration

Recording-related options (command-specific):

• exec/template --record-file <path>: Save recording JSONL after execution.
• exec/template --record-level <off|key-events-only|full>: Recording granularity.
• replay <record_file> --list: List recorded command output events.
• replay <record_file> --command <cmd> [--mode <mode>]: Replay one command output.

Template Syntax

rauto uses Minijinja, which is compatible with Jinja2.

Example configure_vlan.j2:

conf t
{% for vlan in vlans %}
vlan {{ vlan.id }}
 name {{ vlan.name }}
{% endfor %}
end

Example variables:

{
  "vlans": [
    { "id": 10, "name": "Marketing" },
    { "id": 20, "name": "Engineering" }
  ]
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT