Merge pull request #138 from sdcio/addsdctoolssection

Add cli-tools section

Author: steiler

docs/cli-tools/index.md

@@ -0,0 +1,17 @@
+# CLI Tools
+
+SDC ships two official command-line tools that complement the Kubernetes-based control plane.
+
+| | [sdc-lite](sdc-lite.md) | [kubectl-sdc](kubectl-sdc.md) |
+|---|---|---|
+| **What it is** | Standalone CLI for YANG-based config work | `kubectl` plugin for SDC on Kubernetes |
+| **Requires Kubernetes** | No | Yes |
+| **Requires a live device** | No | No (reads from data-server) |
+| **Primary audience** | Network engineers, CI pipelines, offline workflows | Operators managing live SDC-managed targets |
+| **Key capabilities** | Schema loading, config validation, format conversion, diffing, blame | Running config retrieval, blame, deviation inspection and revert |
+
+## When to use which
+
+Use **`sdc-lite`** when you want to work with YANG schemas and device configurations without a running Kubernetes cluster — for example, to validate a config file in CI, convert between formats (JSON, XML, JSON-IETF), or explore what a set of intents produces before pushing them.
+
+Use **`kubectl-sdc`** when you have a live cluster with SDC installed and want to inspect the state of managed targets — for example, to trace which intent owns a given config leaf, retrieve the running config from a device, or detect and revert deviations.

docs/cli-tools/kubectl-sdc.md

@@ -0,0 +1,66 @@
+# kubectl-sdc
+
+[`kubectl-sdc`](https://github.com/sdcio/kubectl-sdc) is a `kubectl` plugin that extends the Kubernetes CLI with SDC-specific commands. It provides visibility into the state of SDC-managed targets directly from the command line, without needing to query raw Kubernetes resources.
+
+## Use cases
+
+- **Inspect running config** — retrieve the actual configuration present on a managed device, in a human-readable format.
+- **Trace intent ownership** — use `blame` to see which Config CR (or the device itself) is the source of each configuration leaf, and detect where higher-priority intents are overriding others.
+- **Detect and revert deviations** — list configuration paths where the device has drifted from its intended state, and selectively revert them.
+
+## Installation
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sdcio/kubectl-sdc/main/install.sh | sh
+```
+
+Alternatively, if you have Go installed:
+
+```bash
+go install github.com/sdcio/kubectl-sdc/cmd/kubectl-sdc@main
+```
+
+Once installed, `kubectl sdc` is available as a `kubectl` plugin. The install script also installs `kubectl_complete-sdc` for tab-completion support.
+
+## Key commands
+
+| Command | Description |
+|---|---|
+| `kubectl sdc blame --target <name>` | Tree view of the running config showing which intent owns each leaf |
+| `kubectl sdc runningconfig --target <name>` | Retrieve the running config from the data-server |
+| `kubectl sdc deviation --target <name>` | List deviations (drifts between intended and actual config) for a target |
+| `kubectl sdc apply -f <file>` | Apply a `TargetClearDeviation` manifest to revert selected deviations |
+
+Both `blame` and `deviation` support `--filter-*` flags for narrowing output by path, leaf name, or owner, and an `--interactive` mode backed by a fuzzy finder.
+
+## Workflow example
+
+The following walkthrough inspects a live SDC-managed target, finds a deviation, and reverts it.
+
+```bash
+# 1. See the running config for a target in xpath format
+kubectl sdc runningconfig --target srl1 --format xpath
+
+# 2. Check which intent owns each config leaf — filter to just the interface subtree
+kubectl sdc blame --target srl1 --filter-path /interface
+
+# 3. List all deviations on the target
+kubectl sdc deviation --target srl1
+
+# 4. Narrow down to deviations under /interface only
+kubectl sdc deviation --target srl1 --filter-path /interface
+
+# 5. Render the selected deviations as a TargetClearDeviation manifest
+kubectl sdc deviation --target srl1 --filter-path /interface --format resource-yaml
+
+# 6. Apply the manifest to revert the deviations
+kubectl sdc deviation --target srl1 --filter-path /interface --format resource-yaml \
+  | kubectl sdc apply -f -
+```
+
+!!! note
+    All commands use the current `kubectl` context and namespace.
+
+## Further reference
+
+Full command reference, filtering options, and interactive mode documentation are available in the [kubectl-sdc GitHub repository](https://github.com/sdcio/kubectl-sdc).

docs/cli-tools/sdc-lite.md

@@ -0,0 +1,77 @@
+# sdc-lite
+
+[`sdc-lite`](https://github.com/sdcio/sdc-lite) is a standalone CLI tool for working with network operating system (NOS) configurations based on YANG schemas. It runs entirely on your local machine — no Kubernetes cluster or live device connection required.
+
+## Use cases
+
+- **Validate configs offline** — check a configuration file against a YANG schema before pushing it to a device or submitting it to a CI pipeline.
+- **Convert between formats** — load a config in one format (e.g. `json_ietf`) and output it in another (e.g. `xml` or `json`).
+- **Inspect and diff intents** — load multiple config intents at different priorities and see the merged result, or diff it against a baseline running config.
+- **Trace intent ownership** — use `blame` to see which intent is the source of each config leaf in the merged result.
+
+## Installation
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sdcio/sdc-lite/main/install.sh | bash
+```
+
+Alternatively, if you have Go installed:
+
+```bash
+go install github.com/sdcio/sdc-lite@latest
+```
+
+Shell completions (bash, zsh, fish) are installed automatically by the install script.
+
+## Key commands
+
+| Command | Description |
+|---|---|
+| `sdc-lite schema load -t <target> -f <schema.yaml>` | Load a YANG schema and associate it with a target |
+| `sdc-lite schema list` | List all loaded schemas |
+| `sdc-lite config load -t <target> --file <path> --file-format <fmt> --intent-name <name>` | Load a config file as a named intent |
+| `sdc-lite config validate -t <target>` | Validate the merged config against the schema |
+| `sdc-lite config diff -t <target>` | Show a diff between the intent config and the running baseline |
+| `sdc-lite config show -t <target> -o json -a` | Show the full merged configuration |
+| `sdc-lite config blame -t <target>` | Show which intent owns each config leaf |
+| `sdc-lite target show -t <target>` | Show target details (schema, intents) |
+| `sdc-lite target remove -t <target>` | Remove a target and its associated state |
+
+## Workflow example
+
+The following walkthrough loads a Nokia SR Linux schema, applies a running config as a baseline, overlays a config intent, and inspects the result.
+
+```bash
+# 1. Load the YANG schema for SR Linux 24.10.1 and associate it with "router1"
+sdc-lite schema load -t router1 \
+  -f https://raw.githubusercontent.com/sdcio/config-server/refs/heads/main/example/schemas/schema-nokia-srl-24.10.1.yaml
+
+# 2. Load the device's running config as the lowest-priority baseline intent
+sdc-lite config load -t router1 \
+  --file https://raw.githubusercontent.com/sdcio/sdc-lite/refs/tags/v0.1.0/data/config/running/running_srl_01.json \
+  --file-format json \
+  --intent-name running
+
+# 3. Load a config intent at higher priority (ethernet-1/1 VLAN config)
+sdc-lite config load -t router1 \
+  --file https://raw.githubusercontent.com/sdcio/sdc-lite/refs/tags/v0.1.0/data/config/additions/srl_01.json \
+  --file-format json \
+  --intent-name config1 \
+  --priority 50
+
+# 4. Validate the merged config against the schema
+sdc-lite config validate -t router1
+
+# 5. Diff the intent additions against the running baseline
+sdc-lite config diff -t router1 --type patch
+
+# 6. Blame — see which intent owns each config leaf under /interface
+sdc-lite config blame -t router1 -p /interface
+
+# 7. Clean up
+sdc-lite target remove -t router1
+```
+
+## Further reference
+
+Full command reference and additional examples are available in the [sdc-lite GitHub repository](https://github.com/sdcio/sdc-lite).

docs/examples/1_k8s_srl.md

@@ -269,3 +269,7 @@ EOF
 
 [containerlab]: (https://containerlab.dev/install/)
 [kind]: (https://kind.sigs.k8s.io/)
+
+## Next steps
+
+Once your targets are configured, use [`kubectl-sdc`](../cli-tools/kubectl-sdc.md) to inspect the running config, trace intent ownership with `blame`, and detect or revert deviations.

docs/examples/2_k8s_sros.md

@@ -10,6 +10,9 @@ SDC will need to interact with a device that talks `YANG`. You can use physical,
 
 [containerlab]: (https://containerlab.dev/install/)
 
+!!!tip
+    Once your targets are up and running, use [`kubectl-sdc`](../cli-tools/kubectl-sdc.md) to inspect running config, trace intent ownership with `blame`, and detect or revert deviations.
+
 ## SDC on Kubernetes
 Install the [k8s-collocated](../install/3_k8s_installation.md) environment using a [kind][kind] cluster 
 

docs/getting-started/basic-usage.md

@@ -2,12 +2,14 @@
 The following examples demonstrate the basic usage of SDC in a scenario where a Nokia SR Linux node is being configured via SDC installed in a Kind based Kubernetes cluster.
 
 ## Prerequisites
- Please ensure that [Docker](https://docs.docker.com) is installed and running on your system. An installation guide can be found in the [Install Docker Engine](https://docs.docker.com/engine/install/) page. Also ensure [post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/) are followed, so that the current user can run docker commands without sudo.
+ Please ensure that [Docker](https://docs.docker.com) is installed and running on your system. An installation guide can be found in the [Install Docker Engine](https://docs.docker.com/engine/install/) page.
+
+!!!tip
+    If you want to explore and validate SDC configurations without a running Kubernetes cluster, check out [sdc-lite](../cli-tools/sdc-lite.md) — a standalone CLI tool for offline config validation, diffing, and format conversion.
 
  Furthermore, the following tools are required to be installed on your system:
  - [jq](https://stedolan.github.io/jq/) - a lightweight and flexible command-line JSON processor.
 
-
 ## Kind
 [kind](https://kind.sigs.k8s.io/) is a tool for running local Kubernetes clusters using Docker container “nodes”. `kind` was primarily designed for testing Kubernetes itself, but may be used for local development or CI.
 

docs/user-guide/deviation.md

@@ -32,7 +32,7 @@ SDC will automatically reapply the Config CR when a NOT-APPLIED deviation is det
 
 SDC will treat the deviation as part of the active configuration. 
 
-To clear a deviation we can select the deviations using the clear deviation logic in kubectl-sdc
+To clear a deviation we can select the deviations using the clear deviation logic in `kubectl-sdc`. See the [kubectl-sdc CLI tool](../cli-tools/kubectl-sdc.md) for installation and usage details.
 
 [kubectl-sdc deviation](https://github.com/sdcio/kubectl-sdc/blob/main/README.md#deviation)
 

docs/user-guide/troubleshooting.md

@@ -18,12 +18,13 @@ v1alpha1.inv.sdcio.dev                 Local                          True
 ```
 
 ### Deployment
-SDC is deployed in the `sdc-system` namespace. If successful, you should see 3 running containers similar to this:
+The sdc components are deployed in the `sdc-system` namespace. 
+Check if they are running.
 
 ```bash
 kubectl get pods -n sdc-system
 ```
-There should be a config-server in the Ready state.
+There should be a 3 pods in Running state
 ```
 NAME                          READY   STATUS    RESTARTS   AGE
 api-server-6d7db47894-xj8wg   1/1     Running   0          38h
@@ -32,13 +33,13 @@ data-server-controller-0      2/2     Running   0          38h
 ```
 
 ### Service
-For the APIServer a Service is referenced, this reference must resolve to the config-server.
+For the APIServer a Service is referenced, this reference must resolve to the api-server .
 Via the Endpoints the association to the pod can be verified.
 ```bash
-kubectl get -n sdc-system endpoints api-server -o yaml
+kubectl get -n sdc-system endpoints api-server  -o yaml
 ```
 
-The Subsets addresses must list the api-server pod.
+The Subsets addresses must list the config-server pod.
 ```yaml
 apiVersion: v1
 kind: Endpoints

mkdocs.yml

@@ -33,6 +33,10 @@ nav:
     - Deviation: user-guide/deviation.md
     - Disable Validation: user-guide/disablevalidation.md
     - Troubeshooting: user-guide/troubleshooting.md
+  - CLI Tools:
+    - Overview: cli-tools/index.md
+    - sdc-lite: cli-tools/sdc-lite.md
+    - kubectl-sdc: cli-tools/kubectl-sdc.md
   - System architecture:
       - Design: system-architecture/architecture.md
       - Components: