Start Here

This is the runner entry point.

Prerequisites

Python 3.11 or later: https://www.python.org/downloads/windows/ . Check "Add python.exe to PATH" during install.
Git: https://git-scm.com/download/win

These docs use py. If py is not recognized on your machine, try python instead.

Get the Code

Clone the repo into C:\NetOpsForge or another simple Windows path.

git clone https://github.com/JT-BFS/NetOpsForge.git C:\NetOpsForge
cd C:\NetOpsForge

Windows Setup (first time)

If PowerShell blocks Activate.ps1, use .\.venv\Scripts\activate.bat instead.

cd C:\NetOpsForge
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install --upgrade pip
py -m pip install -r requirements.txt

Validate Your Setup

py -m netopsforge doctor
python scripts/validate-all.py

Success usually looks like doctor reporting your setup is OK, and validate-all.py ending with ALL MUST CHECKS PASSED.

Note: Use python (not py) for validate-all.py so it runs within the activated venv.

Store Device Credentials

NetOpsForge uses Windows Credential Manager to store device credentials securely. Credentials are never stored in files.

Using the interactive wizard (recommended)

py -m netopsforge credential add

Follow the prompts to enter a credential name, username, and password.

Using cmdkey directly

cmdkey /generic:"NetOpsForge/core-sw-01" /user:"admin" /pass:"yourpassword"

Verify credentials are stored

cmdkey /list | Select-String "NetOpsForge"

Each pack references credentials by name (e.g., NetOpsForge/core-sw-01). The credential_ref field in a pack YAML must match exactly.

Run a Safe Example (dry run)

This does not connect to any device. Success usually looks like the pack commands being printed and the command exiting with no errors.

py -m netopsforge run packs\examples\cisco-ios-bgp-neighbor-check.yml --dry-run

Daily Use

If PowerShell blocks Activate.ps1, use .\.venv\Scripts\activate.bat instead.

cd C:\NetOpsForge
.\.venv\Scripts\Activate.ps1

What to Do After Validation Passes

Once doctor and validate-all.py both pass:

Try a dry run to see how packs work without connecting to devices
Store credentials for a real device using py -m netopsforge credential add
Copy a starter pack from packs/starters/ and customize it for your device
Run your pack with py -m netopsforge run packs/your-pack.yml

Output files are saved to the logs/ directory when the pack has save_to_file: true.

Pack Quality Tools

Validate a pack before running

py -m netopsforge validate packs\your-pack.yml

Lint a pack for style and security issues

py -m netopsforge lint packs\your-pack.yml
py -m netopsforge lint packs\        # lint all packs at once

Lint checks for hardcoded IPs, insecure SSL settings, missing validation rules, and other best practices.

Compare two pack versions

py -m netopsforge diff packs\v1.yml packs\v2.yml
py -m netopsforge diff packs\v1.yml packs\v2.yml --changelog

The --changelog flag produces a Markdown summary useful for PR descriptions.

View the dependency graph

If your packs declare depends_on in their metadata, you can see the full dependency tree:

py -m netopsforge graph packs\
py -m netopsforge graph packs\ --validate   # check for circular dependencies
py -m netopsforge graph packs\ --order      # print safe execution order

Quick Glossary

Term	What It Means
Pack	A YAML file that defines what commands to run on which device
Dry run	Test a pack without connecting to any device (`--dry-run` flag)
Credential ref	The name used to look up a username/password in Windows Credential Manager
Platform	The type of device (e.g., `cisco_ios_xe` for IOS XE routers/switches)
Governance	Rules that control which commands are allowed or blocked
Schema	The structure rules that every pack file must follow
Starter pack	A template pack you copy and customize for your own use
Validate	Check that a pack follows the correct structure before running it
Lint	Check a pack for style, security, and best-practice issues
Pack graph	A diagram showing which packs depend on which other packs
depends_on	Optional metadata field listing packs that must run before this one
Diff	A side-by-side comparison of two pack versions showing what changed
RBAC	Role-based access control — controls who can run which packs

Next Step

If you want to make repository changes, use CONTRIBUTING.md.

Docs deploy to GitHub Pages only after a PR is merged into main.