How to Run AI-Infra-Guard from the CLI: Complete Command-Line Guide

AI-Infra-Guard provides a Go-based CLI built on the Cobra framework that allows you to execute security scans directly from the terminal using the scan sub-command or run a persistent WebSocket service using the webserver sub-command after building the binary with go build.

The Tencent/AI-Infra-Guard repository ships with a native command-line interface that enables direct invocation of the scanning engine without writing additional code. Whether you need ad-hoc security assessments or a continuous monitoring service, understanding how to run AI-Infra-Guard from the CLI is essential for integrating the tool into CI/CD pipelines and automated security workflows.

Building the CLI Binary

Before executing commands, compile the Go source into an executable. The entry point at cmd/cli/main.go initializes the Cobra command structure by calling cmd.Execute().

go build -o ai-infra-guard ./cmd/cli/main.go

This produces the ai-infra-guard binary in your current directory. The build process follows the standard Go toolchain configuration as implemented in the repository's service architecture.

Running One-Off Security Scans

The scan sub-command, implemented in cmd/cli/cmd/scan.go, executes immediate vulnerability assessments against specified targets. This mode creates a Task object internally and routes it through the internal task manager, outputting structured JSON results to stdout.

./ai-infra-guard scan -t http://127.0.0.1:8088

• The -t flag specifies the target URL for assessment.
• The command prints a comprehensive report containing detected vulnerabilities, MCP findings, and prompt-security evaluations upon completion.

Starting the Web Server Mode

For persistent operation or agent integration, use the webserver sub-command defined in cmd/cli/cmd/webserver.go. This starts an HTTP service that accepts WebSocket connections for remote job submission.

./ai-infra-guard webserver --server 127.0.0.1:8088

• The --server flag accepts an IP:PORT pair; the default is 127.0.0.1:8088.
• Once active, agents connect via ws://127.0.0.1:8088/ws to submit scan tasks programmatically.

CLI Architecture and Global Configuration

The root command in cmd/cli/cmd/root.go establishes the Cobra framework foundation and registers global flags such as --config. This architecture allows both sub-commands to share common configuration contexts while maintaining distinct operational logic.

Key implementation files:

• cmd/cli/main.go – Binary entry point that initializes the command structure.
• cmd/cli/cmd/root.go – Root command definition and global flag setup.
• cmd/cli/cmd/scan.go – Scan execution logic and task orchestration.
• cmd/cli/cmd/webserver.go – HTTP service initialization and WebSocket handling.

End-to-End Workflow Example

Combine both modes for a complete testing cycle:

1. Build the binary:

go build -o aig ./cmd/cli/main.go

2. Start the web server in the background:

./aig webserver --server 127.0.0.1:8088 &

3. Execute a scan against the local service:

./aig scan -t http://127.0.0.1:8088

This workflow validates both the CLI scanning capability and the web service availability in a single session.

Summary

• Compile the CLI using go build -o ai-infra-guard ./cmd/cli/main.go to generate the executable.
• Use ./ai-infra-guard scan -t <url> for immediate, standalone security assessments that output JSON reports.
• Launch persistent services with ./ai-infra-guard webserver --server <addr> to enable WebSocket agent connections.
• The Cobra-based architecture in cmd/cli/cmd/root.go provides unified global flags and extensible sub-command registration.
• Both operational modes share the same binary, selected at runtime via sub-command arguments.

Frequently Asked Questions

What is the difference between the scan and webserver commands?

The scan command executes a one-time vulnerability assessment against a target URL and prints results immediately to stdout, while the webserver command starts a persistent HTTP service that accepts WebSocket connections for remote job submission. Both commands are implemented as separate sub-commands in the Cobra framework but share the same binary entry point in cmd/cli/main.go.

How do I specify a target URL for scanning?

Use the -t flag followed by the target URL when invoking the scan sub-command, as implemented in cmd/cli/cmd/scan.go. For example: ./ai-infra-guard scan -t http://127.0.0.1:8088. This parameter is processed to create the internal Task object that drives the scanning engine.

Can agents connect to the CLI when running in webserver mode?

Yes, once the webserver is started with ./ai-infra-guard webserver --server <addr>, agents can establish WebSocket connections to ws://<addr>/ws and submit scan jobs programmatically according to the implementation in cmd/cli/cmd/webserver.go. The server listens on the specified address and handles incoming WebSocket traffic.

Where is the CLI entry point located in the source code?

The entry point resides in cmd/cli/main.go, which calls cmd.Execute() to launch the root command defined in cmd/cli/cmd/root.go. This file initializes the Cobra framework and registers the available sub-commands, including scan and webserver.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}