Agent CLI Reference

Complete command-line reference for the GrantFlow Agent binary. This page documents all commands, flags, and options available.

Command Overview

The GrantFlow Agent provides the following commands:

Command	Description
`enroll`	Enroll the agent with the GrantFlow control plane
`run`	Run the agent (foreground or as service)
`service install`	Install the agent as a system service
`service start`	Start the agent service
`service stop`	Stop the agent service
`service restart`	Restart the agent service
`service status`	Check agent service status
`service uninstall`	Uninstall the agent service
`fix-config`	Fix relative paths in configuration file
`version`	Display agent version information
`help`	Display help for any command

enroll

Enroll the agent with the GrantFlow control plane. This command exchanges the enrollment token for an mTLS certificate and creates the agent configuration file.

Syntax

agent enroll [flags]

Flags

Flag	Type	Required	Description
`--enrollment-url`	string	Yes	Enrollment service URL (e.g., `https://enrollment.grantflow.cloud/enroll`)
`--tenant-id`	string	Yes	Tenant ID (GUID format)
`--agent-id`	string	Yes	Agent ID (unique identifier for this agent)
`--token`	string	Yes	Enrollment token (obtained from GrantFlow Admin UI)
`--output`, `-o`	string	No	Directory to save certificate files (default: `./certs`)
`--config-dir`	string	No	Directory to save configuration file (default: `./config`)
`--key-size`	int	No	RSA key size in bits (default: `4096`)
`--server`	string	No	Control plane URL (default: `https://localhost:8443`)
`--server-name`	string	No	Override TLS server name for verification
`--verbose`, `-v`	boolean	No	Enable verbose logging during enrollment

Examples

Windows:

.\agent.exe enroll `
  --enrollment-url https://enrollment.grantflow.cloud/enroll `
  --tenant-id 5abfdf65-694b-4c35-9b9b-e65af70c8306 `
  --agent-id agent-001 `
  --token ept_gvKQp3u7eMZYkLfhP-7VLcCZMYgKv_1N2KjzP6ySlL4

Linux:

sudo ./agent enroll \
  --enrollment-url https://enrollment.grantflow.cloud/enroll \
  --tenant-id 5abfdf65-694b-4c35-9b9b-e65af70c8306 \
  --agent-id agent-001 \
  --token ept_gvKQp3u7eMZYkLfhP-7VLcCZMYgKv_1N2KjzP6ySlL4

Custom paths:

./agent enroll \
  --enrollment-url https://enrollment.grantflow.cloud/enroll \
  --tenant-id 5abfdf65-694b-4c35-9b9b-e65af70c8306 \
  --agent-id agent-001 \
  --token ept_... \
  --output /etc/grantflow/certs \
  --config-dir /etc/grantflow

With custom control plane URL:

./agent enroll \
  --enrollment-url https://enrollment.grantflow.cloud/enroll \
  --tenant-id 5abfdf65-694b-4c35-9b9b-e65af70c8306 \
  --agent-id agent-001 \
  --token ept_... \
  --server https://agents.grantflow.cloud

Verbose mode (for troubleshooting):

./agent enroll \
  --enrollment-url https://enrollment.grantflow.cloud/enroll \
  --tenant-id 5abfdf65-694b-4c35-9b9b-e65af70c8306 \
  --agent-id agent-001 \
  --token ept_... \
  --verbose

Output

On success, the command creates:

Configuration file: config/agent-config.yaml with absolute paths
Certificate files:
- certs/agent-cert.pem - Agent mTLS certificate
- certs/agent-key.pem - Agent private key
- certs/ca-chain.pem - CA certificate chain

Enrolling agent: agent-001
Tenant ID: 5abfdf65-694b-4c35-9b9b-e65af70c8306
Enrollment URL: https://enrollment.grantflow.cloud/enroll
Generating 4096-bit RSA key pair...
Creating Certificate Signing Request...
Submitting enrollment request...
✓ Private key saved: C:\Program Files\GrantFlow Agent\certs\agent-key.pem
✓ Certificate saved: C:\Program Files\GrantFlow Agent\certs\agent-cert.pem
✓ CA chain saved: C:\Program Files\GrantFlow Agent\certs\ca-chain.pem
✓ Certificate chain verified successfully
✓ Configuration saved: C:\Program Files\GrantFlow Agent\config\agent-config.yaml

✓ Enrollment complete!

To run the agent, simply use:
  agent run

Or specify a custom config:
  agent run --config C:\Program Files\GrantFlow Agent\config\agent-config.yaml

Note: The verbose output above is shown when using the --verbose flag. Without it, only the checkmarks (✓) and file paths are displayed.

Exit Codes

Code	Meaning
`0`	Success
`1`	Enrollment failed (network, invalid token, etc.)

Enrollment Token Expiry

Enrollment tokens expire after 1 hour. If enrollment fails with a token validation error, generate a new token from the GrantFlow Admin UI.

run

Run the agent in the foreground (for testing) or as a service (when started by service manager).

Syntax

agent run [flags]

Flags

Flag	Type	Required	Description
`--config`	string	No	Path to configuration file (default: `./config/agent-config.yaml`)
`--service`	boolean	No	Run as service (used by service manager, not for manual use)

Examples

Run in foreground (for testing):

# Windows
.\agent.exe run

# Linux
sudo ./agent run

With custom config path:

./agent run --config /etc/grantflow/agent-config.yaml

Output

The agent logs to:

Windows (foreground): Console output
Windows (service): C:\Windows\Temp\grantflow-agent-YYYYMMDD.log
Linux (foreground): Console output
Linux (service): systemd journal (journalctl -u grantflow-agent)

2025/11/03 14:30:52 === GrantFlow Agent Started ===
2025/11/03 14:30:52 Agent ID: agent-001
2025/11/03 14:30:52 Tenant ID: 5abfdf65-694b-4c35-9b9b-e65af70c8306
2025/11/03 14:30:52 Control Plane: https://agents.grantflow.cloud
2025/11/03 14:30:53 Successfully connected to control plane
2025/11/03 14:30:53 Agent registered and ready to receive jobs

Exit Codes

Code	Meaning
`0`	Normal shutdown (SIGTERM/SIGINT received)
`1`	Fatal error (certificate not found, connection failed, etc.)

Testing Before Service Installation

Use agent run to test the agent in foreground mode before installing it as a service. Press Ctrl+C to stop.

service

Manage the agent as a system service (Windows Service or systemd unit).

service install

Install the agent as a system service.

Syntax

agent service install [flags]

Flags

Flag	Type	Required	Description
`--config`	string	No	Path to configuration file (default: `./config/agent-config.yaml`)

Examples

# Windows
cd "C:\Program Files\GrantFlow Agent"
.\agent.exe service install

# Linux
cd /opt/grantflow-agent
sudo ./agent service install

Service Configuration

Windows:

Service name: GrantFlowAgent
Display name: GrantFlow Agent
Start type: Automatic
Service account: NT AUTHORITY\LocalService
Restart on failure: Yes

Linux:

Service name: grantflow-agent
Unit type: simple
Start on boot: Use systemctl enable grantflow-agent
User: Root or dedicated service user

Output

✓ Service installed successfully
  Name: GrantFlowAgent
  Executable: C:\Program Files\GrantFlow Agent\agent.exe
  Config: C:\Program Files\GrantFlow Agent\config\agent-config.yaml

Logs will be written to: C:\Windows\Temp\grantflow-agent-*.log

To start the service, run:
  agent service start

service start

Start the agent service.

Syntax

agent service start

Examples

# Windows
.\agent.exe service start

# Linux
sudo ./agent service start

Output

✓ Service started successfully

To view logs, check: C:\Windows\Temp\grantflow-agent-20251103.log
PowerShell command to view latest log:
  Get-Content (Get-ChildItem C:\Windows\Temp\grantflow-agent-*.log | Sort-Object LastWriteTime -Descending | Select-Object -First 1).FullName

service stop

Stop the agent service.

Syntax

agent service stop

Examples

# Windows
.\agent.exe service stop

# Linux
sudo ./agent service stop

Output

✓ Service stopped successfully

service restart

Restart the agent service (stop then start).

Syntax

agent service restart

Examples

# Windows
.\agent.exe service stop
.\agent.exe service start

# Linux (or use systemctl)
sudo systemctl restart grantflow-agent

service status

Check the status of the agent service.

Syntax

agent service status

Examples

# Windows
.\agent.exe service status

# Linux
sudo ./agent service status

Output

Service Status: Running

Possible statuses:

Running - Service is running
Stopped - Service is stopped
Not Installed - Service is not installed

service uninstall

Uninstall the agent service. The service must be stopped before uninstalling.

Syntax

agent service uninstall

Examples

# Windows
.\agent.exe service stop
.\agent.exe service uninstall

# Linux
sudo ./agent service stop
sudo ./agent service uninstall

Output

✓ Service uninstalled successfully

Uninstall Does Not Remove Files

Uninstalling the service only removes the service registration. Configuration files, certificates, and the agent binary are preserved. Delete them manually if needed.

fix-config

Convert relative paths in an existing configuration file to absolute paths. This is useful for configuration files created with older agent versions that used relative paths.

Syntax

agent fix-config [flags]

Flags

Flag	Type	Required	Description
`--config`	string	Yes	Path to configuration file to fix

Examples

# Windows
cd "C:\Program Files\GrantFlow Agent"
.\agent.exe fix-config --config .\config\agent-config.yaml

# Linux
cd /opt/grantflow-agent
sudo ./agent fix-config --config ./config/agent-config.yaml

What It Does

Reads the existing configuration file
Converts relative certificate paths to absolute paths
Verifies that certificate files exist at the new paths
Creates a backup of the original configuration (.backup extension)
Saves the updated configuration

Output

Current configuration:
  Tenant ID: 5abfdf65-694b-4c35-9b9b-e65af70c8306
  Agent ID: agent-001
  Server URL: https://agents.grantflow.cloud
  Certificate: certs\agent-cert.pem
  Key: certs\agent-key.pem
  CA: certs\ca-chain.pem

Converting certificate path:
  From: certs\agent-cert.pem
  To:   C:\Program Files\GrantFlow Agent\certs\agent-cert.pem

Converting key path:
  From: certs\agent-key.pem
  To:   C:\Program Files\GrantFlow Agent\certs\agent-key.pem

Converting CA path:
  From: certs\ca-chain.pem
  To:   C:\Program Files\GrantFlow Agent\certs\ca-chain.pem

Verifying files exist at new paths...
✓ Certificate file found: C:\Program Files\GrantFlow Agent\certs\agent-cert.pem
✓ Key file found: C:\Program Files\GrantFlow Agent\certs\agent-key.pem
✓ CA file found: C:\Program Files\GrantFlow Agent\certs\ca-chain.pem

✓ Backup created: C:\Program Files\GrantFlow Agent\config\agent-config.yaml.backup
✓ Config file updated: C:\Program Files\GrantFlow Agent\config\agent-config.yaml

Updated configuration:
  Certificate: C:\Program Files\GrantFlow Agent\certs\agent-cert.pem
  Key: C:\Program Files\GrantFlow Agent\certs\agent-key.pem
  CA: C:\Program Files\GrantFlow Agent\certs\ca-chain.pem

✓ Config file fixed successfully!

Exit Codes

Code	Meaning
`0`	Success
`1`	Configuration file not found or invalid
`2`	Certificate files not found at resolved paths

When to Use

New enrollments (since recent versions) automatically create configuration files with absolute paths. This command is only needed for older installations with relative paths that cause issues when running as a Windows service.

version

Display the agent version information.

Syntax

agent version

Examples

# Windows
.\agent.exe version

# Linux
./agent version

Output

GrantFlow Agent
Version: 1.0.0
Build: 20251103-142305
Commit: a1b2c3d
Go Version: go1.21.5
OS/Arch: windows/amd64

help

Display help information for any command.

Syntax

agent help [command]

Examples

# General help
./agent help

# Help for specific command
./agent help enroll
./agent help service
./agent help service install

Global Flags

These flags are available for all commands:

Flag	Type	Description
`--help`, `-h`	boolean	Display help for the command
`--version`, `-v`	boolean	Display version information

Examples

# Display help for enroll command
./agent enroll --help

# Display version
./agent --version

Configuration File Format

The agent configuration file is in YAML format. It is automatically created by the enroll command.

Location

Windows: C:\Program Files\GrantFlow Agent\config\agent-config.yaml
Linux: /opt/grantflow-agent/config/agent-config.yaml

Example

tenantId: "5abfdf65-694b-4c35-9b9b-e65af70c8306"
agentId: "agent-001"
serverUrl: "https://agents.grantflow.cloud"
certPath: "C:\\Program Files\\GrantFlow Agent\\certs\\agent-cert.pem"
keyPath: "C:\\Program Files\\GrantFlow Agent\\certs\\agent-key.pem"
caPath: "C:\\Program Files\\GrantFlow Agent\\certs\\ca-chain.pem"

Fields

Field	Type	Required	Description
`tenantId`	string	Yes	Tenant ID (GUID format)
`agentId`	string	Yes	Agent ID (unique identifier)
`serverUrl`	string	Yes	Control plane URL
`certPath`	string	Yes	Absolute path to agent certificate
`keyPath`	string	Yes	Absolute path to agent private key
`caPath`	string	Yes	Absolute path to CA certificate chain

Absolute Paths Required

All certificate paths must be absolute paths. Relative paths will fail when the agent runs as a service because the working directory is different from the installation directory.

Environment Variables

The agent does not use environment variables for configuration. All configuration is stored in the YAML configuration file.

For proxy configuration, use system-level proxy settings:

Windows:

Set in Internet Options → Connections → LAN Settings
Or use netsh winhttp set proxy

Linux:

Set http_proxy, https_proxy, no_proxy environment variables
Or configure system-wide in /etc/environment

Exit Codes

All agent commands use standard exit codes:

Code	Meaning
`0`	Success
`1`	General error
`2`	Configuration error
`3`	Network error
`4`	Certificate error
`130`	Interrupted by user (Ctrl+C)

Command Cheat Sheet

Quick reference for common operations:

# Installation
./agent enroll --enrollment-url URL --tenant-id ID --agent-id ID --enrollment-key KEY
./agent service install
./agent service start

# Management
./agent service status
./agent service stop
./agent service start
./agent service restart

# Logs (Windows)
Get-Content C:\Windows\Temp\grantflow-agent-$(Get-Date -Format "yyyyMMdd").log -Wait -Tail 50

# Logs (Linux)
sudo journalctl -u grantflow-agent -f

# Update
./agent service stop
# Replace binary
./agent service start

# Troubleshooting
./agent run                              # Test in foreground
./agent fix-config --config path         # Fix relative paths
sc.exe qc GrantFlowAgent                 # Check service account (Windows)
./agent version                          # Check version

# Uninstall
./agent service stop
./agent service uninstall
# Delete files manually if needed

Command Overview​

enroll​

Syntax​

Flags​

Examples​

Output​

Exit Codes​

run​

Syntax​

Flags​

Examples​

Output​

Exit Codes​

service​

service install​

Syntax​

Flags​

Examples​

Service Configuration​

Output​

service start​

Syntax​

Examples​

Output​

service stop​

Syntax​

Examples​

Output​

service restart​

Syntax​

Examples​

service status​

Syntax​

Examples​

Output​

service uninstall​

Syntax​

Examples​

Output​

fix-config​

Syntax​

Flags​

Examples​

What It Does​

Output​

Exit Codes​

version​

Syntax​

Examples​

Output​

help​

Syntax​

Examples​

Global Flags​

Examples​

Configuration File Format​

Location​

Example​

Fields​

Environment Variables​

Exit Codes​

Command Cheat Sheet​

See Also​

Command Overview

enroll

Syntax

Flags

Examples

Output

Exit Codes

run

Syntax

Flags

Examples

Output

Exit Codes

service

service install

Syntax

Flags

Examples

Service Configuration

Output

service start

Syntax

Examples

Output

service stop

Syntax

Examples

Output

service restart

Syntax

Examples

service status

Syntax

Examples

Output

service uninstall

Syntax

Examples

Output

fix-config

Syntax

Flags

Examples

What It Does

Output

Exit Codes

version

Syntax

Examples

Output

help

Syntax

Examples

Global Flags

Examples

Configuration File Format

Location

Example

Fields

Environment Variables

Exit Codes

Command Cheat Sheet

See Also