add inspect CLI command

Author: networmix

docs/reference/cli.md

@@ -1,6 +1,6 @@
 # Command Line Interface
 
-NetGraph provides a command-line interface for running scenarios and generating results directly from the terminal.
+NetGraph provides a command-line interface for inspecting, running, and analyzing scenarios directly from the terminal.
 
 ## Installation
 
@@ -12,7 +12,20 @@ pip install ngraph
 
 ## Basic Usage
 
-The primary command is `run`, which executes scenario files:
+The CLI provides two primary commands:
+
+- `inspect`: Analyze and validate scenario files without running them
+- `run`: Execute scenario files and generate results
+
+### Quick Start
+
+```bash
+# Inspect a scenario to understand its structure
+python -m ngraph inspect my_scenario.yaml
+
+# Run a scenario after inspection
+python -m ngraph run my_scenario.yaml --results
+```
 
 ```bash
 # Run a scenario (execution only, no file output)
@@ -34,6 +47,60 @@ python -m ngraph run scenario.yaml --results --stdout
 
 ## Command Reference
 
+### `inspect`
+
+Analyze and validate a NetGraph scenario file without executing it.
+
+**Syntax:**
+
+```bash
+python -m ngraph inspect <scenario_file> [options]
+```
+
+**Arguments:**
+
+- `scenario_file`: Path to the YAML scenario file to inspect
+
+**Options:**
+
+- `--detail`, `-d`: Show detailed information including complete node/link tables and step parameters
+- `--help`, `-h`: Show help message
+
+**What it does:**
+
+The `inspect` command loads and validates a scenario file, then provides information about:
+
+- **Scenario metadata**: Seed configuration and deterministic behavior
+- **Network structure**: Node/link counts, enabled/disabled breakdown, hierarchy analysis
+- **Capacity statistics**: Link and node capacity analysis with min/max/mean/total values
+- **Risk groups**: Network resilience groupings and their status
+- **Components library**: Available components for network modeling
+- **Failure policies**: Configured failure scenarios and their rules
+- **Traffic matrices**: Demand patterns and traffic flows
+- **Workflow steps**: Analysis pipeline and step-by-step execution plan
+
+In detail mode (`--detail`), shows complete tables for all nodes and links with capacity and connectivity information.
+
+**Examples:**
+
+```bash
+# Basic inspection
+python -m ngraph inspect my_scenario.yaml
+
+# Detailed inspection with comprehensive node/link tables and step parameters
+python -m ngraph inspect my_scenario.yaml --detail
+
+# Inspect with verbose logging
+python -m ngraph inspect my_scenario.yaml --verbose
+```
+
+**Use cases:**
+
+- **Scenario validation**: Verify YAML syntax and structure
+- **Network debugging**: Analyze blueprint expansion and node/link creation
+- **Capacity analysis**: Review network capacity distribution and connectivity
+- **Workflow preview**: Examine analysis steps before execution
+
 ### `run`
 
 Execute a NetGraph scenario file.
@@ -212,6 +279,41 @@ python -m ngraph run scenario.yaml --results analysis.json --stdout
 
 The CLI executes the complete workflow defined in your scenario file, running all steps in sequence and accumulating results. This automates complex network analysis tasks without manual intervention.
 
+### Recommended Workflow
+
+1. **Inspect first**: Always use `inspect` to validate and understand your scenario
+2. **Debug issues**: Use detailed inspection to troubleshoot network expansion problems
+3. **Run after validation**: Execute scenarios only after successful inspection
+4. **Iterate**: Use inspection during scenario development to verify changes
+
+```bash
+# Development workflow
+python -m ngraph inspect my_scenario.yaml --detail  # Validate and debug
+python -m ngraph run my_scenario.yaml --results        # Execute after validation
+```
+
+### Debugging Scenarios
+
+When developing complex scenarios with blueprints and hierarchical structures:
+
+```bash
+# Check if scenario loads correctly
+python -m ngraph inspect scenario.yaml
+
+# Debug network expansion issues
+python -m ngraph inspect scenario.yaml --detail --verbose
+
+# Verify workflow steps are configured correctly
+python -m ngraph inspect scenario.yaml --detail | grep -A 5 "Workflow Steps"
+```
+
+The `inspect` command will catch common issues like:
+- Invalid YAML syntax
+- Missing blueprint references
+- Incorrect node/link patterns
+- Workflow step configuration errors
+- Risk group and policy definition problems
+
 ## See Also
 
 - [DSL Reference](dsl.md) - Scenario file syntax and structure