Command Line Flags Overview#

The following flags are available for agent client configuration. Each flag is bound to a Viper configuration key of the same name, enabling consistent access throughout the application. CLI flags take precedence over environment variables and configuration file values.

Server-Recommended Settings#

The agent fetches configuration from the server's /configuration endpoint during startup and on reload. The server can recommend timeout, retry, and circuit breaker settings that override the agent's local configuration. When server recommendations are present, the agent logs the applied values and rebuilds its API client with the new settings. This ensures agents can adapt to server capacity and network conditions without requiring manual reconfiguration.

Backward Compatibility#

The agent supports deprecated underscore-style flag aliases (e.g., --api_token, --data_path) for backward compatibility with existing deployments and scripts. These aliases are hidden and will display a deprecation warning when used. Values set via deprecated flags are automatically bridged to their canonical kebab-case equivalents (e.g., --api-token, --data-path).

For all new deployments, scripts, and configuration examples, use the kebab-case flag names. The underscore-style aliases are maintained solely for transition purposes and may be removed in a future major version.

Benchmark Caching#

The agent uses persistent disk caching for benchmark results, storing them at {data_path}/benchmark_cache.json. Cached benchmarks survive agent restarts and can be retried automatically if submission to the server fails. This prevents unnecessary re-runs of the computationally expensive benchmarking process.

Use the --force-benchmark flag to bypass the cache and force a fresh benchmark run. This is useful when hardware changes occur or when you need to verify current performance. Server-initiated reloads automatically force fresh benchmarks to ensure up-to-date results are submitted.

Deferred Benchmarking#

When --defer-benchmarks is enabled, the agent splits benchmarking into two phases to minimize startup time:

Phase 1 — Capability Detection (startup): Instead of running a full GPU benchmark, the agent executes RunCapabilityDetection(), which invokes hashcat --hash-info --machine-readable to enumerate all supported hash types in seconds. For each discovered hash type, a placeholder cache entry is created with SpeedHs=1 and Placeholder=true, and these placeholder results are submitted to the server immediately. The agent then enters the main task loop without waiting for GPU benchmarks to complete.

Phase 2 — Background Benchmarking (idle): When --benchmark-while-idle is also enabled (the default), the RunBackgroundBenchmarks() goroutine processes placeholder entries from the cache one hash type at a time. Before each run, it calls waitForIdle(), which polls the agent's activity state and blocks until the agent is idle (CurrentActivityWaiting). Priority ordering ensures common types (MD5/0, SHA1/100, NTLM/1000) are benchmarked first, followed by remaining types in ascending numeric order. After each single-type benchmark completes, the placeholder cache entry is replaced with real results and submitted to the server incrementally. Background benchmarking pauses automatically when a task starts (goroutine is cancelled) and restarts after task completion.

--force-benchmark overrides deferred mode — if set, the agent always runs a full benchmark at startup regardless of --defer-benchmarks.

Note for air-gapped environments: Deferred benchmarking requires no external network access during capability detection. Placeholder results are submitted to the CipherSwarm server in the same manner as full benchmark results, so the server can begin assigning tasks immediately. Background benchmarks update results incrementally as they complete during idle periods.

Configuration Precedence#

Viper merges configuration from multiple sources in the following order of precedence (highest to lowest):

1. Command line flags
2. Environment variables (automatically mapped by Viper)
3. Configuration file (YAML, e.g., cipherswarmagent.yaml)
4. Default values (set in code)

This means a value set via a CLI flag will override the same value set via an environment variable or config file.

Usage Examples#

Setting Flags via Command Line#

cipherswarmagent \
  --api-token=YOUR_TOKEN \
  --api-url=https://swarm.example.com \
  --data-path=/var/lib/cipherswarm \
  --gpu-temp-threshold=75 \
  --debug \
  --status-timer=30

Short flag forms are available for many options, e.g. -a for --api-token, -u for --api-url, -d for --debug.

Using Environment Variables#

Viper automatically maps environment variables to configuration keys. For example:

export API_TOKEN=YOUR_TOKEN
export API_URL=https://swarm.example.com
export DATA_PATH=/var/lib/cipherswarm
export GPU_TEMP_THRESHOLD=75
cipherswarmagent

Using a Configuration File#

Create a YAML file (e.g., cipherswarmagent.yaml):

api_token: YOUR_TOKEN
api_url: https://swarm.example.com
data_path: /var/lib/cipherswarm
gpu_temp_threshold: 75
debug: true
status_timer: 30

Then run:

cipherswarmagent --config /path/to/cipherswarmagent.yaml

Overriding Config File with CLI Flags#

Any CLI flag will override the corresponding value in the config file or environment variable:

cipherswarmagent --config /etc/cipherswarmagent.yaml --debug=false --status-timer=5

Best Practices#

• Use CLI flags for quick overrides or scripting.
• Use environment variables for containerized or cloud deployments.
• Use a configuration file for persistent, version-controlled settings.
• Combine methods as needed; CLI flags always take precedence.
• Review the agent's --help output for the most up-to-date flag list and descriptions.

Implementation Details#

Each flag is defined in the agent's cmd/root.go using Cobra, then bound to a Viper key with the same name. Default values are set in lib/config/config.go. At runtime, Viper merges all sources, and the agent reads configuration via Viper's API, ensuring consistent and predictable behavior across all deployment scenarios. For more details, see the agent's configuration implementation and configuration management code.