CLI, Configuration, and Environment Reference
Purpose and Scope
This page orients operators and DAG authors to the Airflow command line, environment-variable-driven configuration, and runtime value management surfaces. The official documentation treats the command line as a reference entry point for administering an Airflow installation: commands are grouped under the airflow executable, with families such as api-server, assets, backfill, config, connections, dags, and other operational areas. Provider packages can add their own command groups; for example, the Amazon provider documentation exposes an aws-auth-manager command group for managing AWS auth manager resources. The practical reader problem is deciding which surface to use for a given change: a local CLI command, an environment/configuration setting, a provider-specific command, or an Airflow Variable.
Configuration and Variables are related but not interchangeable. Airflow configuration controls platform behavior, component startup, logging, authentication, scheduling, and deployment-wide settings. Variables are named runtime values stored in Airflow and read by DAG code or managed by users through the API and UI. The source paths for this page focus on the public Variables surface, which is a useful model for how configuration-like operational data is exposed safely: schemas validate fields, route handlers enforce permissions, services preserve invariants, and the UI links users to the same domain concept. Sources: airflow-core/src/airflow/api_fastapi/core_api/datamodels/variables.py, airflow-core/src/airflow/api_fastapi/core_api/routes/public/variables.py, airflow-core/src/airflow/api_fastapi/core_api/services/public/variables.py, airflow-core/src/airflow/ui/src/pages/Variables/index.tsx
The official CLI and environment variables reference should be read as the canonical command catalog for a released Airflow version. In the repository, documentation publication is itself modeled as an architecture: package documentation is published from the apache-airflow repository, placed in the live documentation bucket, proxied through CloudFront, and surfaced on https://airflow.apache.org. That matters for configuration work because operators should match the CLI reference, configuration reference, and provider command reference to the exact Airflow and provider versions they run, rather than mixing source-branch behavior with another release's documentation. Sources: docs/images/documentation_architecture.py
Relevant Source Files
docs/images/documentation_architecture.py- Generates the documentation architecture diagram, showing how package docs from the Apache Airflow repository are published to live docs infrastructure and why release-versioned docs are the authoritative operator reference.airflow-core/src/airflow/ui/src/pages/Variables/index.tsx- Exports the Variables page entry point used by the Airflow UI, tying runtime key/value management to a user-facing administration surface.airflow-core/src/airflow/api_fastapi/core_api/datamodels/variables.py- Defines request and response models for Variables, including value serialization, redaction, field limits,team_name, and collection/import response shapes.airflow-core/src/airflow/api_fastapi/core_api/routes/public/variables.py- Defines the public FastAPI router for Variables, including route prefix, list/get/delete behavior, pagination, sorting, filtering, access checks, and action logging hooks.airflow-core/src/airflow/api_fastapi/core_api/services/public/variables.py- Implements service-level update and bulk behavior, including immutable keys, update masks, validation, existence checks, and use of the shared bulk service pattern.
Core Primitives
The Airflow CLI is the local administrative entry point. In official documentation it is presented as airflow GROUP_OR_COMMAND ..., with command groups organized around platform resources and components. For day-to-day operations, the most relevant groups are config, for reading and validating configuration; connections, for managing external service connection records; dags, for inspecting and managing DAG state; assets, for data-aware scheduling operations; and component commands such as api-server or dag-processor. Provider documentation may add additional groups, so the complete command surface is the union of core Airflow and installed providers.
Environment variables are a deployment-time configuration mechanism. They are commonly used in containers, Helm deployments, systemd services, and CI jobs because they let operators inject values without editing a static configuration file in place. Treat environment variables as infrastructure configuration, not as DAG data exchange. If a setting changes how the API server, scheduler, triggerer, DAG processor, logging, authentication, or database behavior works, it belongs in configuration. If a DAG needs a user-managed runtime value, prefer an Airflow Variable, a Connection, a Param, or a secrets backend depending on the data's purpose and sensitivity.
Airflow Variables are a public runtime value primitive with explicit API contracts. VariableBody accepts a key, a JSON-compatible value, optional description, and optional team_name; the source limits keys with ID_LEN and team_name to 50 characters. The body serializes value using the val alias, while VariableResponse exposes the stored value through the value alias and includes description, is_encrypted, and team_name. The response validator redacts dictionary-like JSON and scalar values before returning them, which is a critical distinction from naïvely exposing stored values. Sources: airflow-core/src/airflow/api_fastapi/core_api/datamodels/variables.py
The team_name field illustrates how configuration governs a runtime management surface. The model validator checks conf.getboolean("core", "multi_team") and rejects team_name when multi-team mode is disabled, returning a validation error that tells the user to contact an administrator. That means an operator-level configuration choice changes which Variable payloads are valid. When documenting or automating Variable creation, include this constraint: payloads that work in a multi-team deployment may fail in a single-team deployment, even if the key and value are otherwise valid. Sources: airflow-core/src/airflow/api_fastapi/core_api/datamodels/variables.py
CLI and Configuration Workflow
Start with the official CLI reference for the version you run, then use airflow config commands for configuration inspection and maintenance. The official command list includes config get-value, config lint, config list, and config update, which correspond to common operator tasks: retrieve the effective value for a setting, check configuration health, enumerate settings, and update configuration where supported. In scripted environments, prefer commands that report current state before mutating it, because Airflow deployments often combine a config file, environment variables, secrets, container defaults, and chart-managed values.
A safe configuration workflow has four phases. First, identify whether the setting is core Airflow configuration, provider configuration, a Connection, a Variable, or DAG code. Second, check the versioned docs that match your release; the repository's documentation architecture shows package docs flowing from this repository to the live documentation site through the release publishing process. Third, verify the effective value from the runtime environment, not only from source-controlled defaults. Fourth, apply the change through the deployment system that owns it, such as a Helm values file, a container environment variable, a systemd unit, or an Airflow API/CLI operation for mutable metadata. Sources: docs/images/documentation_architecture.py
Use provider CLI documentation when a command manages provider-specific infrastructure. The Amazon provider example shows a provider command group, aws-auth-manager, with subcommands such as init-avp and update-avp-schema. Those commands are not generic Airflow configuration; they operate on provider resources and may require provider-specific authentication, cloud permissions, and installed package versions. This separation is important operationally: a missing provider package can remove the command group entirely, while a core airflow config command should remain tied to the installed Airflow distribution.
A concise example flow for an operator might be: inspect a configuration key with airflow config get-value SECTION KEY; lint the current configuration with airflow config lint; list related settings with airflow config list; and then update the value in the deployment-owned source of truth. For runtime metadata, use the relevant resource command or API instead of configuration. For example, manage a Variable through the UI, REST API, or a supported CLI path rather than encoding DAG-specific data into global configuration variables.
Variables API and UI as a Configuration-Adjacent Surface
The public Variables API is routed under /variables using an AirflowRouter tagged as Variable. The route module imports shared query parameters for limit, offset, key pattern search, key prefix search, and sorting, along with security dependencies such as requires_access_variable, requires_access_variable_bulk, and a readable variables filter. That structure shows the expected behavior of an administrative metadata surface: users can list and retrieve records, access is filtered by authorization, and API responses follow declared models rather than returning raw database rows. Sources: airflow-core/src/airflow/api_fastapi/core_api/routes/public/variables.py
The single-variable endpoints make the operational contract concrete. GET /variables/{variable_key} retrieves one Variable by key and returns 404 when it is absent. DELETE /variables/{variable_key} deletes by key, returns 204 on success, and also returns 404 when no row is deleted. The delete endpoint uses action logging and a delete permission dependency. The source comments explain that these public API handlers intentionally avoid Variable.delete, Variable.get, and Variable.set because those methods are intended for the task execution environment, not for API-server administration. Sources: airflow-core/src/airflow/api_fastapi/core_api/routes/public/variables.py
The service layer protects invariants that clients should not try to bypass. update_orm_from_pydantic requires the key in the request body to match the URI parameter and rejects mismatches with 400. It loads the existing row, returns 404 if the Variable does not exist, validates either the full VariableBody or a partial model constrained by the update mask, and declares key as a non-updatable field. Bulk behavior is implemented by BulkVariableService, which categorizes requested keys against existing rows before applying create, update, or delete style actions. Sources: airflow-core/src/airflow/api_fastapi/core_api/services/public/variables.py
The UI entry point for Variables is intentionally thin in the targeted source: index.tsx re-exports Variables from the local page module. Even that small file is useful for orientation because it confirms Variables are not only a backend model; they are an explicit page in the Airflow UI. When teaching users where to put runtime key/value data, point them to the Variables UI for manual administration and to the public API for automation. For secrets or credentials, use Connections or a secrets backend instead of treating Variables as a secure configuration store by default. Sources: airflow-core/src/airflow/ui/src/pages/Variables/index.tsx
Compact Reference
| Surface | Use it for | Source-backed behavior |
|---|---|---|
airflow config ... | Inspecting and maintaining Airflow configuration from the command line | Official docs list get-value, lint, list, and update; verify behavior against the versioned docs for your release. |
| Environment variables | Deployment-owned configuration injection | Best used for component settings and containerized deployments; keep runtime DAG data in Variables, Params, Connections, or secrets backends. |
| Provider CLI groups | Provider-specific resources and setup | Official provider docs can add command groups, such as Amazon's aws-auth-manager; installed providers determine availability. |
/variables API | Automated Variable management | Router exposes Variable-tagged routes, access dependencies, pagination/filtering/sorting imports, and model-backed responses. |
| Variables UI page | Manual Variable administration | The UI page is exported from the Variables page entry point, making Variables a first-class user-facing resource. |
| Variable API model or function | Contract |
|---|---|
VariableBody | Request body with key, JSON-compatible value, optional description, and optional team_name. |
VariableResponse | Response serializer with redacted value, description, is_encrypted, and team_name. |
VariableCollectionResponse | Collection response with variables and total_entries. |
VariablesImportResponse | Import response with created_variable_keys, import_count, and created_count. |
update_orm_from_pydantic | Updates an existing Variable, validates update masks, rejects key mismatches, and preserves key as immutable. |
BulkVariableService | Categorizes requested keys by existence before bulk operations. |
Operational Guidance and Next Steps
For administrators, the main rule is to keep each value in the narrowest appropriate surface. Platform behavior belongs in Airflow configuration and should be changed through the deployment mechanism that owns the running components. External-service credentials usually belong in Connections or a secrets backend. DAG-specific runtime values can be Variables when they are not better expressed as Params or assets. Use the CLI reference for local commands, the configuration reference for settings, provider docs for provider command groups, and the Variables API/UI for mutable runtime key/value metadata.
Before automating configuration or Variable changes, decide how you will audit and roll them back. CLI commands are convenient, but a production Airflow deployment is often managed by infrastructure-as-code, Helm, or container orchestration. API-based Variable automation should handle 400 validation errors, 404 missing records, redacted response values, and authorization failures. If you are writing documentation for your team, include both the command/API call and the owning source of truth so readers know whether they are making a temporary runtime edit or a persistent deployment change.
Next, read the pages on connections, variables-xcom-and-params, secrets-backends-and-masking, and rest-api-and-openapi-clients. Together they clarify the boundary between configuration, runtime metadata, secret material, and API automation. For deployment-specific configuration, pair this page with production-deployment, kubernetes-and-helm, and docker-stack so operators can translate the same Airflow settings into the environment mechanism used by their installation.