# Fabric Orchestrator CLI User Guide

This guide covers the `fabric-orch` command-line interface for exploring YANG paths and managing Arista EVPN-VXLAN fabrics via gNMI.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Environment Variables](#environment-variables)
- [Commands Overview](#commands-overview)
- [discover capabilities](#discover-capabilities)
- [discover get](#discover-get)
- [discover set](#discover-set)
- [discover subscribe](#discover-subscribe)
- [discover paths](#discover-paths)
- [Output Formats](#output-formats)
- [Error Handling](#error-handling)
- [Best Practices](#best-practices)

---

## Installation

Ensure you have Python 3.12+ and `uv` installed, then:

```bash
# Clone the repository
git clone https://gitea.arnodo.fr/Damien/fabric-orchestrator.git
cd fabric-orchestrator

# Install dependencies
uv sync

# Verify installation
uv run fabric-orch --version
```

---

## Quick Start

```bash
# Set environment variables (optional but recommended)
export GNMI_TARGET="172.16.0.50:6030"
export GNMI_USERNAME="admin"
export GNMI_PASSWORD="admin"

# List device capabilities
uv run fabric-orch discover capabilities

# Get interface state
uv run fabric-orch discover get --path "/interfaces/interface[name=Ethernet1]/state"

# Show common YANG paths reference
uv run fabric-orch discover paths
```

---

## Environment Variables

The CLI supports these environment variables to avoid passing credentials repeatedly:

| Variable        | Description                         | Default    |
| --------------- | ----------------------------------- | ---------- |
| `GNMI_TARGET`   | Target device in `host:port` format | (required) |
| `GNMI_USERNAME` | Username for gNMI authentication    | `admin`    |
| `GNMI_PASSWORD` | Password for gNMI authentication    | `admin`    |

**Example:**
```bash
export GNMI_TARGET="leaf1:6030"
export GNMI_USERNAME="admin"
export GNMI_PASSWORD="admin"

# Now you can omit --target, --username, --password
uv run fabric-orch discover capabilities
```

---

## Commands Overview

```
fabric-orch
└── discover                    # YANG path discovery tools
    ├── capabilities            # List device capabilities
    ├── get                     # Get config/state data
    ├── set                     # Set configuration
    ├── subscribe               # Subscribe to updates
    └── paths                   # Show common paths reference
```

---

## discover capabilities

List device capabilities and supported YANG models.

### Usage

```bash
fabric-orch discover capabilities [OPTIONS]
```

### Options

| Option                     | Short | Description                            |
| -------------------------- | ----- | -------------------------------------- |
| `--target`                 | `-t`  | Target device (host:port)              |
| `--username`               | `-u`  | Username for authentication            |
| `--password`               | `-p`  | Password for authentication            |
| `--insecure/--no-insecure` |       | Skip TLS verification (default: True)  |
| `--output`                 | `-o`  | Output format: pretty, json, file:path |

### Examples

```bash
# Basic usage with all options
uv run fabric-orch discover capabilities \
  --target 172.16.0.50:6030 \
  --username admin \
  --password admin \
  --insecure

# Using environment variables
export GNMI_TARGET="172.16.0.50:6030"
uv run fabric-orch discover capabilities

# Output as JSON
uv run fabric-orch discover capabilities --output json

# Save to file
uv run fabric-orch discover capabilities --output file:capabilities.json
```

### Sample Output

```
Device Capabilities - 172.16.0.50:6030

gNMI Version: 0.8.0
Supported Encodings: json_ietf, json, proto

Supported Models (156):

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Model Name                        ┃ Organization    ┃ Version    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ arista-exp-eos-evpn               │ Arista Networks │ 2023-01-01 │
│ arista-exp-eos-mlag               │ Arista Networks │ 2023-01-01 │
│ arista-exp-eos-vxlan              │ Arista Networks │ 2023-01-01 │
│ openconfig-interfaces             │ OpenConfig      │ 2.4.3      │
│ openconfig-network-instance       │ OpenConfig      │ 1.1.0      │
│ ...                               │ ...             │ ...        │
└───────────────────────────────────┴─────────────────┴────────────┘
```

---

## discover get

Get configuration or state data at a YANG path.

### Usage

```bash
fabric-orch discover get [OPTIONS]
```

### Options

| Option                     | Short | Description                                  |
| -------------------------- | ----- | -------------------------------------------- |
| `--target`                 | `-t`  | Target device (host:port)                    |
| `--username`               | `-u`  | Username for authentication                  |
| `--password`               | `-p`  | Password for authentication                  |
| `--insecure/--no-insecure` |       | Skip TLS verification                        |
| `--output`                 | `-o`  | Output format: pretty, json, file:path       |
| `--path`                   | `-P`  | YANG path to get data from **(required)**    |
| `--type`                   | `-T`  | Data type: config, state, all (default: all) |
| `--depth`                  | `-d`  | Maximum depth (not implemented yet)          |

### Examples

```bash
# Get all data at a path
uv run fabric-orch discover get \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface[name=Ethernet1]"

# Get config only
uv run fabric-orch discover get \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface[name=Ethernet1]" \
  --type config

# Get state only
uv run fabric-orch discover get \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface[name=Ethernet1]/state" \
  --type state

# Get BGP neighbor state
uv run fabric-orch discover get \
  --target 172.16.0.50:6030 \
  --path "/network-instances/network-instance[name=default]/protocols/protocol[identifier=BGP][name=BGP]/bgp/neighbors/neighbor/state"

# Get VXLAN VNI mappings
uv run fabric-orch discover get \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface[name=Vxlan1]/arista-vxlan/vlan-to-vnis"

# Save output to file
uv run fabric-orch discover get \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface" \
  --output file:interfaces.json

# Machine-readable JSON output
uv run fabric-orch discover get \
  --target 172.16.0.50:6030 \
  --path "/system/config" \
  --output json | jq '.notification[0].update[0].val'
```

### Path Syntax

YANG paths use a specific syntax:

- **Basic path**: `/interfaces/interface`
- **With key**: `/interfaces/interface[name=Ethernet1]`
- **Multiple keys**: `/protocols/protocol[identifier=BGP][name=BGP]`
- **Nested path**: `/interfaces/interface[name=Ethernet1]/state/oper-status`

### Common Paths

| Category   | Path                                                                                                                          | Description     |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------- |
| Interfaces | `/interfaces/interface[name=Ethernet1]/state`                                                                                 | Interface state |
| BGP        | `/network-instances/network-instance[name=default]/protocols/protocol[identifier=BGP][name=BGP]/bgp/neighbors/neighbor/state` | BGP neighbors   |
| VXLAN      | `/interfaces/interface[name=Vxlan1]/arista-vxlan/vlan-to-vnis`                                                                | VNI mappings    |
| MLAG       | `/arista/eos/mlag/config`                                                                                                     | MLAG config     |
| System     | `/system/config/hostname`                                                                                                     | Hostname        |

---

## discover set

Set configuration at a YANG path.

> ⚠️ **Warning**: This command modifies device configuration. Use with caution!

### Usage

```bash
fabric-orch discover set [OPTIONS]
```

### Options

| Option                     | Short | Description                                          |
| -------------------------- | ----- | ---------------------------------------------------- |
| `--target`                 | `-t`  | Target device (host:port)                            |
| `--username`               | `-u`  | Username for authentication                          |
| `--password`               | `-p`  | Password for authentication                          |
| `--insecure/--no-insecure` |       | Skip TLS verification                                |
| `--output`                 | `-o`  | Output format: pretty, json, file:path               |
| `--path`                   | `-P`  | YANG path to set **(required)**                      |
| `--value`                  | `-v`  | Value to set (JSON or string) **(required)**         |
| `--operation`              | `-O`  | Operation: update, replace, delete (default: update) |
| `--dry-run/--no-dry-run`   |       | Dry-run mode (default: True)                         |

### Examples

```bash
# Dry-run (default) - shows what would be set
uv run fabric-orch discover set \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface[name=Ethernet1]/config/description" \
  --value "Uplink to Spine1"

# Actually apply the change
uv run fabric-orch discover set \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface[name=Ethernet1]/config/description" \
  --value "Uplink to Spine1" \
  --no-dry-run

# Set JSON value
uv run fabric-orch discover set \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface[name=Ethernet1]/config" \
  --value '{"description": "Uplink", "enabled": true}' \
  --no-dry-run

# Replace operation (overwrites existing config)
uv run fabric-orch discover set \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface[name=Ethernet1]/config" \
  --value '{"description": "New config"}' \
  --operation replace \
  --no-dry-run

# Delete configuration
uv run fabric-orch discover set \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface[name=Ethernet1]/config/description" \
  --value "" \
  --operation delete \
  --no-dry-run
```

### Operations

| Operation | Description                                 |
| --------- | ------------------------------------------- |
| `update`  | Merge with existing configuration (default) |
| `replace` | Replace existing configuration at path      |
| `delete`  | Delete configuration at path                |

### Dry-Run Mode

By default, the `set` command runs in **dry-run mode**, which shows what would be changed without applying it. This is a safety feature.

```bash
# Dry-run output
⚠ DRY-RUN MODE - No changes will be applied

SET (dry-run) /interfaces/interface[name=Ethernet1]/config/description

Operation: update
Value: Uplink to Spine1

Use --no-dry-run to apply this change
```

---

## discover subscribe

Subscribe to YANG path updates in real-time.

### Usage

```bash
fabric-orch discover subscribe [OPTIONS]
```

### Options

| Option                     | Short | Description                                                  |
| -------------------------- | ----- | ------------------------------------------------------------ |
| `--target`                 | `-t`  | Target device (host:port)                                    |
| `--username`               | `-u`  | Username for authentication                                  |
| `--password`               | `-p`  | Password for authentication                                  |
| `--insecure/--no-insecure` |       | Skip TLS verification                                        |
| `--output`                 | `-o`  | Output format: pretty, json, file:path                       |
| `--path`                   | `-P`  | YANG path(s) to subscribe to (can repeat) **(required)**     |
| `--mode`                   | `-m`  | Mode: on-change, sample, target-defined (default: on-change) |
| `--interval`               | `-i`  | Sample interval in seconds (for sample mode)                 |
| `--count`                  | `-c`  | Number of updates before exiting                             |

### Examples

```bash
# Subscribe to interface operational status changes
uv run fabric-orch discover subscribe \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface/state/oper-status" \
  --mode on-change

# Sample interface counters every 10 seconds
uv run fabric-orch discover subscribe \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface[name=Ethernet1]/state/counters" \
  --mode sample \
  --interval 10

# Subscribe to multiple paths
uv run fabric-orch discover subscribe \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface/state/oper-status" \
  --path "/network-instances/network-instance[name=default]/protocols/protocol[identifier=BGP][name=BGP]/bgp/neighbors/neighbor/state/session-state"

# Get only 5 updates then exit
uv run fabric-orch discover subscribe \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface/state/counters" \
  --mode sample \
  --interval 5 \
  --count 5

# Output as JSON (useful for piping)
uv run fabric-orch discover subscribe \
  --target 172.16.0.50:6030 \
  --path "/interfaces/interface/state/oper-status" \
  --output json
```

### Subscription Modes

| Mode             | Description                                       |
| ---------------- | ------------------------------------------------- |
| `on-change`      | Receive updates only when values change (default) |
| `sample`         | Receive periodic updates at specified interval    |
| `target-defined` | Let the device decide the update strategy         |

### Important Note for Arista EOS

For **ON_CHANGE** subscriptions on Arista EOS, use native paths **without** module prefixes:

```bash
# ✅ Correct - native path
--path "/interfaces/interface[name=Ethernet1]/state"

# ❌ Incorrect - with module prefix (may fail)
--path "/openconfig-interfaces:interfaces/interface[name=Ethernet1]/state"
```

### Stopping Subscriptions

Press `Ctrl+C` to stop a subscription gracefully.

---

## discover paths

Display a reference table of commonly used YANG paths for Arista EOS.

### Usage

```bash
uv run fabric-orch discover paths
```

This command doesn't require a target connection - it displays a static reference.

### Example Output

```
Common YANG Paths for Arista EOS

┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Category   ┃ Path                                                             ┃ Notes                     ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Interfaces │ /interfaces/interface[name=Ethernet1]/state                      │ Full interface state      │
│ Interfaces │ /interfaces/interface[name=Ethernet1]/state/oper-status          │ Operational status        │
│ Interfaces │ /interfaces/interface[name=Ethernet1]/state/counters             │ Interface counters        │
│ Loopbacks  │ /interfaces/interface[name=Loopback0]                            │ Loopback interface        │
│ VLANs      │ /network-instances/network-instance[name=default]/vlans/vlan     │ All VLANs                 │
│ BGP        │ .../bgp/neighbors/neighbor/state                                 │ All BGP neighbors         │
│ VXLAN      │ /interfaces/interface[name=Vxlan1]/arista-vxlan/vlan-to-vnis     │ VLAN-to-VNI mappings      │
│ VXLAN      │ /interfaces/interface[name=Vxlan1]/arista-vxlan/config           │ VXLAN config              │
│ MLAG       │ /arista/eos/mlag/config                                          │ MLAG config (config only) │
│ EVPN       │ /arista/eos/evpn                                                 │ EVPN config (config only) │
│ System     │ /system/config/hostname                                          │ System hostname           │
└────────────┴──────────────────────────────────────────────────────────────────┴───────────────────────────┘
```

---

## Output Formats

All discovery commands support three output formats via the `--output` / `-o` option:

### Pretty (default)

Rich formatted output with syntax highlighting and tables.

```bash
uv run fabric-orch discover get --path "/system/config" --output pretty
```

### JSON

Machine-readable JSON output, suitable for piping to `jq` or other tools.

```bash
uv run fabric-orch discover get --path "/system/config" --output json | jq '.'
```

### File

Save output directly to a file.

```bash
uv run fabric-orch discover get --path "/interfaces/interface" --output file:interfaces.json
```

---

## Error Handling

The CLI provides helpful error messages with hints:

### Connection Errors

```
✗ Connection Error: Failed to connect to 172.16.0.50:6030

Hints:
  • Check if the target is reachable
  • Verify gNMI is enabled on the device
  • Check credentials
  • Try --insecure flag for self-signed certs
```

### Path Errors

```
✗ Path Error: Path not found or invalid: /invalid/path

Hints:
  • Use 'discover capabilities' to see supported models
  • Check path syntax (e.g., /interfaces/interface[name=Ethernet1])
  • Try a parent path first
```

---

## Best Practices

### 1. Use Environment Variables

Set credentials once to avoid repetition:

```bash
export GNMI_TARGET="172.16.0.50:6030"
export GNMI_USERNAME="admin"
export GNMI_PASSWORD="admin"
```

### 2. Start with Capabilities

Before exploring paths, check what models the device supports:

```bash
uv run fabric-orch discover capabilities
```

### 3. Explore Incrementally

Start with broad paths and narrow down:

```bash
# Start broad
uv run fabric-orch discover get --path "/interfaces"

# Then narrow down
uv run fabric-orch discover get --path "/interfaces/interface[name=Ethernet1]"

# Then specific leaves
uv run fabric-orch discover get --path "/interfaces/interface[name=Ethernet1]/state/oper-status"
```

### 4. Use Dry-Run for Set Operations

Always test with dry-run first:

```bash
# Test first
uv run fabric-orch discover set --path "..." --value "..."

# Then apply
uv run fabric-orch discover set --path "..." --value "..." --no-dry-run
```

### 5. Save Exploration Results

Save interesting discoveries to files for documentation:

```bash
uv run fabric-orch discover get --path "/arista/eos/evpn" --output file:evpn-config.json
```

### 6. Use JSON Output for Scripting

For automation, use JSON output:

```bash
# Get interface names
uv run fabric-orch discover get \
  --path "/interfaces/interface" \
  --output json | jq -r '.notification[0].update[0].val | keys[]'
```

---

## Troubleshooting

### gNMI Not Responding

1. Verify gNMI is enabled on the device:
   ```
   switch# show management api gnmi
   ```

2. Check the correct port (default: 6030 for Arista)

3. Ensure network connectivity:
   ```bash
   nc -zv 172.16.0.50 6030
   ```

### Certificate Issues

For lab environments with self-signed certificates, always use `--insecure`:

```bash
uv run fabric-orch discover capabilities --target leaf1:6030 --insecure
```

### Path Not Found

1. Check path syntax - use exact key names
2. Verify the model is supported: `discover capabilities`
3. Try the parent path first
4. Check if it's config-only or state-only data

---

## See Also

- [YANG Paths Reference](yang-paths.md) - Detailed path documentation
- [gNMI Module README](../src/gnmi/README.md) - Python API documentation