Docs/Agent Setup

Agent Setup

The FlowGuard Agent is a .NET CLI tool that runs locally on your machine or CI/CD pipeline. It handles codebase scanning, flow execution via Playwright, and result reporting.

Prerequisites

.NET 8 SDK or later — dotnet --version should return 8.0+
Chromium — the agent installs Playwright browsers on first run, or you can pre-install with playwright install chromium
FlowGuard account — sign up at app.flowguardians.com

Installation

Install the FlowGuard Agent as a global .NET tool:

Terminal

1"function">dotnet tool install "flag">--global FlowGuard.Agent
2
3"comment"># Verify installation
4"function">flowguard "flag">--version

Authenticate with your FlowGuard account:

Terminal

1"function">flowguard auth login
2"comment"># This opens a browser window for authentication
3"comment"># Your token is stored securely in your system keychain

Running Modes

The agent supports three operating modes:

Scan Mode

Analyzes your codebase and generates flow proposals. Code is analyzed locally and only metadata (page names, route patterns, form fields) is sent to the FlowGuard API.

Terminal

1"function">flowguard "function">scan "flag">--repo ./my-app "flag">--app-id YOUR_APP_ID
2
3"comment"># Options:
4"comment">#   "flag">--repo         Path to your repository root
5"comment">#   "flag">--app-id       Your application ID from the dashboard
6"comment">#   "flag">--include      Glob patterns for files to include (default: auto-detect)
7"comment">#   "flag">--exclude      Glob patterns for files to exclude
8"comment">#   "flag">--max-files    Maximum files to analyze (default: 200)

Run Mode

Executes test flows using Playwright. The agent opens a browser, performs each step, captures screenshots, records API calls, and reports results.

Terminal

1"function">flowguard "function">run "flag">--app-id YOUR_APP_ID "flag">--flow-id FLOW_ID
2
3"comment"># Run all flows:
4"function">flowguard "function">run "flag">--app-id YOUR_APP_ID "flag">--all
5
6"comment"># Options:
7"comment">#   "flag">--app-id       Your application ID
8"comment">#   "flag">--flow-id      Specific flow to "function">run (omit for "flag">--all)
9"comment">#   "flag">--all          Run all active flows
10"comment">#   "flag">--headless     Run browser in headless mode (default: true)
11"comment">#   "flag">--base-url     Override the application base URL
12"comment">#   "flag">--timeout      Step timeout in seconds (default: 30)
13"comment">#   "flag">--parallel     Number of parallel browser instances (default: 1)

Listen Mode

Connects to the FlowGuard hub via SignalR and waits for execution commands. Ideal for CI/CD pipelines and always-on test runners.

Terminal

1"function">flowguard "function">listen "flag">--app-id YOUR_APP_ID
2
3"comment"># Options:
4"comment">#   "flag">--app-id       Your application ID
5"comment">#   "flag">--headless     Run browser in headless mode (default: true)
6"comment">#   "flag">--base-url     Override the application base URL

CLI Reference

Command	Description
`flowguard auth login`	Authenticate with FlowGuard
`flowguard auth logout`	Clear stored credentials
`flowguard scan`	Scan codebase and generate proposals
`flowguard run`	Execute test flows
`flowguard listen`	Listen for remote execution commands
`flowguard status`	Show agent status and configuration
`flowguard --version`	Print version information
`flowguard --help`	Show help for all commands

Code Privacy

In scan mode, your source code is analyzed locally on your machine. Only extracted metadata (page names, route patterns, form field names, and CSS selectors) is sent to the FlowGuard API. Your full source code never leaves your environment.