CLI Reference

Per-command reference for the linuxguard-agent CLI — start, config, probe, and additional commands shipping in subsequent phases.

Per-command reference for the linuxguard-agent binary. Each page documents one command with five mandatory sections: Flags, Environment, Signals, Exit codes, and Examples. Flags, environment variables, signals, and exit codes are verified against the agent source.

For day-to-day operator workflows (install, configure, deploy, respond), see the lifecycle phases in the left navigation. This section is the canonical destination when you need to look up a flag or env-var mid-task.

Available commands

Command	Purpose	Page
start	Run the LinuxGuard agent in typical service mode or ephemeral (container/Kubernetes) mode.	start
config	Read or mutate individual runtime configuration keys (set, get, unset, list-keys).	config
probe	Check kernel, eBPF, fanotify, netlink, audit, and Linux-capability availability on the host.	probe
enroll	Bind the agent to a tenant via long-lived API key.	enroll
unenroll	Remove the agent from its tenant (currently a placeholder — see page for the operator workaround).	unenroll
support-bundle	Collect a diagnostic archive locally (collect) or upload an existing archive via a presigned S3 URL (upload).	support-bundle
show-config	Print the entire current configuration as indented JSON to stdout.	show-config
status	Report whether the agent process is running (PID-file check + signal-0 probe).	status
--version / -v	Print the agent build version, commit, and build time.	version

For a brief overview of the v3.0 agent commands surface, see Agent Commands. The pages above are the v4.0 canonical reference and supersede that overview for the commands they cover.

Cross-cutting reference pages

The reference pages below document surface that cuts across multiple commands. Each per-command page above links into these from its Signals / Environment / Exit codes sections.

Page	Purpose
signals	Which POSIX signals the agent handles (SIGHUP, SIGTERM, SIGINT), what each handler does, and the 128+signum re-raise convention.
env-variables	Every LINUXGUARD_* environment variable the agent reads, including the LINUXGUARD_ENROLL_TOKEN immediately-unset-after-read protection.
exit-codes	Universal exit codes (0, 1, 2, 130, 143) and per-command divergences (e.g., probe always 0).

Conventions

These conventions apply to every per-command page in this section.

Flag form

User-facing flags are documented in their long form (--api-key, --tenant-id, --environment). The agent source uses urfave/cli/v2's flag plumbing which may expose short aliases internally; only the long forms are part of the public interface and only the long forms are documented here. The --environment flag has one documented alias, --group, preserved for backward compatibility with v3.0 enrollment scripts; see Conventions for the policy.

Environment-variable precedence

For flags that bind to an environment variable (notably --enroll-token → LINUXGUARD_ENROLL_TOKEN, --node-id → LINUXGUARD_NODE_NAME, --api-url → LINUXGUARD_API_URL, --tenant-id → LINUXGUARD_TENANT_ID, --loader-embedded → LINUXGUARD_LOADER_EMBEDDED), an explicit flag value takes precedence over the environment variable. When the flag is omitted, urfave/cli/v2 reads the bound EnvVars entry. When neither is set, the agent uses its built-in default.

LINUXGUARD_ENROLL_TOKEN is a special case: the agent reads it once at startup and immediately calls os.Unsetenv on it so the raw token cannot leak via /proc/<pid>/environ while the agent runs. Do not rely on it being readable after the first read.

Exit-code summary

Code	Convention
0	Success — command completed without error, or the command is non-fatal by design (probe always exits 0; see its page).
1	General error — surfaced via log.Fatal after the agent run returns a non-nil error.
130	SIGINT (Ctrl-C) — interactive cancellation; os.Exit(128 + int(syscall.SIGINT)).
143	SIGTERM — orchestrator-driven shutdown; os.Exit(128 + int(syscall.SIGTERM)).

The 128 + signum convention is the standard shell exit code for signal-induced termination. The agent re-raises caught signals from main (not the goroutine) so containerized PID-1 deployments exit with the conventional code rather than the Go runtime's dieFromSignal exit(2) fallback.

Signal handling

The start command installs handlers for SIGINT, SIGTERM, and SIGHUP via signal.Notify. SIGINT and SIGTERM trigger graceful shutdown and the signal-derived exit code. SIGHUP has two effects in the start process:

1. The active log writer (lumberjack rotator) calls Rotate() to close and reopen the log file descriptor. This enables coexistence with external logrotate.

2. A separate handler re-reads the persisted log level from disk and applies it without a restart.

Other commands (config, probe, enroll, etc.) are one-shot invocations and do not install signal handlers.

---

Related: Agent Commands | Reference | Configure