Fleetctl CLI
Relevant source files
The following files were used as context for generating this wiki page:
Fleetctl is the official command-line interface (CLI) for Fleet, designed to manage hosts, apply infrastructure-as-code configurations, and interact with the Fleet REST API. It serves as a primary tool for IT and security teams to automate device management workflows, such as enrolling devices, deploying software, and running live queries across a distributed fleet of endpoints.
Sources: tools/README.md, articles/managing-linux-desktops-with-gitops.md
The tool is essential for GitOps-native workflows, allowing administrators to express every aspect of Fleet's configuration—including policies, labels, and software packages—as version-controlled YAML files. These files can be applied to a Fleet server to reconcile the environment's state with the desired configuration defined in code.
Sources: articles/managing-linux-desktops-with-gitops.md, cmd/fleetctl/fleetctl/templates/new/README.md
Architecture and Core Logic
Fleetctl functions as a client for the Fleet server. It authenticates using an API token and communicates over HTTPS. The CLI is structured to handle various resource types by parsing YAML definitions and translating them into API requests.
The diagram below illustrates the high-level interaction between the CLI and the Fleet ecosystem:
Fleetctl can be used manually or integrated into CI/CD pipelines (e.g., GitHub Actions, GitLab CI) to automate configuration updates.
Sources: articles/managing-linux-desktops-with-gitops.md, cmd/fleetctl/fleetctl/templates/new/README.md
Key Command Modules
Fleetctl is organized into several primary command groups that manage different aspects of the Fleet lifecycle.
Configuration and Authentication
Before interacting with a Fleet instance, fleetctl must be configured with the server address and user credentials.
| Command | Description |
|---|---|
fleetctl config set | Sets the target Fleet server URL (e.g., --address https://fleet.example.com). |
fleetctl login | Authenticates the user and retrieves an API token for subsequent sessions. |
fleetctl logout | Terminates the current authenticated session. |
Sources: articles/deploy-fleet-on-ubuntu-with-elastic.md:275-276
Infrastructure as Code (GitOps)
The GitOps module allows administrators to manage labels, policies, and team settings through declarative YAML files.
fleetctl apply: Applies a configuration file to the Fleet server. It reconciles the server state to match the file, creating or updating resources as needed.fleetctl gitops: A specialized command for deploying configurations in a GitOps workflow, often supporting dry-runs in Pull Requests.fleetctl generate-gitops: Exports current server configurations into YAML files to facilitate migration to a GitOps model.
Sources: articles/managing-linux-desktops-with-gitops.md, cmd/fleetctl/fleetctl/templates/new/README.md
Package and Agent Management
Fleetctl includes tools for generating installers for the Fleet agent (Orbit/osquery).
fleetctl package: Generates installer packages (e.g.,.pkg,.msi,.deb) for various platforms.fleetctl preview: Runs a local, containerized instance of Fleet and its dependencies for testing or QA purposes.
Sources: tools/README.md, handbook/engineering/releases.md:36-39
Live Queries
Administrators can use fleetctl to run ad-hoc SQL queries against live hosts using osquery. This provides real-time visibility into system states across the entire fleet.
Live queries leverage osquery's table-based system information retrieval.
Sources: tools/README.md, articles/deploy-fleet-on-ubuntu-with-elastic.md
Deployment and Setup
Installation
Fleetctl is distributed as a binary for Linux, macOS, and Windows. It can also be managed via package managers like NPM for specific environments.
Sources: tools/README.md, articles/deploy-fleet-on-ubuntu-with-elastic.md:267-270
Environment Secrets
For automation in CI/CD pipelines, fleetctl relies on specific environment variables for authentication:
| Variable | Description |
|---|---|
FLEET_URL | The URL of the Fleet server instance. |
FLEET_API_TOKEN | The API token for an "API-only" user or GitOps service account. |
Sources: cmd/fleetctl/fleetctl/templates/new/README.md, articles/managing-linux-desktops-with-gitops.md
QA and Local Testing
The fleetctl preview command is a vital tool for the engineering and QA process. It allows users to:
- Start a local Fleet server.
- Target specific versions using the
--tagflag. - Simulate hosts or run without simulated hosts using
--no-hosts.
Sources: handbook/engineering/releases.md:36-41
Conclusion
Fleetctl CLI is the bridge between human administrators, automated pipelines, and the Fleet server. By enabling declarative configuration and live telemetry retrieval, it provides a high-agency management interface that replaces traditional manual UI interactions with scalable, version-controlled operations. Its role in GitOps makes it an indispensable component for managing security and compliance at scale across macOS, Windows, and Linux.
Sources: articles/managing-linux-desktops-with-gitops.md, cmd/fleetctl/fleetctl/templates/new/README.md