Page History

Status

Motivation

Providing the same functionality from the API interface is available via airflowctl. This makes most of the airflow CLI commands redundant, causing duplicate efforts as well as exposing the database directly to the user, making the system insecure, and allowing interaction with database entries without any Role-Based Access Control (RBAC).

Actions were previously defined inAIP-81: Enhanced Security in CLI via Integration of API.

• Local (Process/Administrative) Commands: Process-based commands, allowing users to manage deployments, interact with the DB shell, and perform other administrative functions.
  
• Remote Commands: Any command that can be supported or provided by the Public (Core) API.
  

This proposal reduces maintenance effort by reallocating development focus from the airflow CLI to airflowctl for Remote Commands. This will result in faster delivery of features, reduce code duplication, and strengthen the Airflow Public (Core) API as the single source of truth. Providing functionalities from a secure channel using authentication methods and RBAC.

Main goal is 

Considerations

At a high level:

• Limit the development of airflow CLI commands for Remote commands.
  
• Deprecate airflow CLI commands that overlap with airflowctl.
  
• Provide warnings to users suggesting migration to airflowctl, with a deprecation replacement period.
  
• Ensure functional parity: deprecations  replacement will only happen once equivalent features exist in airflowctl.
  
• Maintain a transition process (via a PR template, see below) to map CLI commands to airflowctl.
  
• Catch up with additional features in the airflow CLI that were not implemented in airflowctl when AIP-81 was introduced.
• Provide migration tooling and mapping `airflow <command> ↔ airflowctl <command>`

What change do you propose to make?

We propose to limit propose limiting the development of the airflow CLI for Remote commands and instead migrate these migrating these commands to a new dedicated tool. airflowctl, which interfaces exclusively with the Airflow Public (Core) API.

.

• Equivalent functionality will be implemented in implemented  airflowctl to ensure no loss of capability.

• New Remote features will only be added to airflowctl (and the API), not to the airflow CLI.

• Keep both CLI and CTL. CLI development will be stopped, and always call CTL.

• Local administrative commands (e.g., database shell, process management) will continue to exist in the airflow CLI.

What problem does it solve?

There will be two sides to this AIP. One is creating a tool to help users migrate to airflowctl more easily, with minimal changes. Second is we will implement the same/mostly the same (Some API limitations could be there) feature and call everything from airflowctl. This will keep CLI in place for remote commands. Nothing will be added to CLI as a remote context anymore.

In the diagram, you can see the main aim of the AIP. Managing the tooling and adding a deprecation warning while ensuring airflowctl has the command can be managed within different projects.

Image Added

Diagram 1: Migration Tool

Image Added

Diagram 2: Replacement Process

Airflow CLI State

The airflow CLI continues functioning and development mainly for admin tasks, such as running components and low-level database management tasks. We will stop developing and include a replacement warning for any feature that can be provided from the API.

What problem does it solve?

The aim is to help users migrate to API based CLI solution of Apache Airflow while preventing duplicate implementation effort from the time we include a replacement warning for any CLI command

.

Why is it needed?

It is to enforce the vision to use the API as the single source of truth for all Remote commands.

Additionally, it aims to simplify maintenance by removing duplicate code paths.

Tooling is needed because of easier migrations. The automations over Airflow CLI should be easier to detect. With the tool, we need to output as much automation as possible while giving proper guidance or replacing them where possible. We cannot fully automate the authentication and running the command, but the command itself can be easily replaced with the new tooling via proper mapping.

Are there any downsides to this change?

Nothing will be changed from the user's perspective. No migration, the Airflow CLI will be able to use CTL out of the box.

Which users are affected by the change?

Any user has been using the

Airflow CLI

with remote commands (any command can be provided from API/airflowctl).

Administrator commands won't be impacted.

How are users affected by the change? (e.g. DB upgrade required?)

What is the level of migration effort (manual and automated) needed for the users to adapt to the breaking changes? (especially in the context of Airflow 3)

• No database upgrade is required: This AIP only impacts the CLI tooling layer. The Airflow metadatabase schema is unaffected.

• No scheduler/webserver/executor upgrade impact beyond normal release upgrades: Users can upgrade Airflow as usual; the only difference is CLI behaviour for Remote commands.

• CLI usage changes:

  • Remote commands (airflow dags …, airflow connections …, airflow pools …, etc.) will emit deprecation warnings and direct users to use airflowctl instead.

  • Local administrative commands (e.g., airflow db shell, airflow info) remain available in the airflow CLI without changes.

• Script & automation updates required: Any custom tooling, automation, or CI/CD scripts that call Remote airflow CLI commands will need to migrate to airflowctl.

• Migration window: Users will have at least three minor (example: from 3. x.x  to 3.x+3.x ) release cycles with warnings before Remote CLI commands are removed entirely.

• Security improvements: Remote operations will go through the API layer, enforcing RBAC and audit logging — this may change access patterns in organisations that currently rely on direct DB access through airflow CLI.x

Other considerations?

• Release of airflowctl: 1.0.0 version of `airflowctl` has been released.
• Backwards Compatibility: CLI deprecation should follow Airflow’s standard deprecation policy (warnings, documentation updates, migration guides).
• Tooling/Automation Impact: Any scripts or automation using airflow CLI remote commands must migrate to airflowctl.
• Documentation & Communication: Clear migration documentation, examples, and communication in release notes/community channels will be required.
• Testing Strategy: Ensure parity between airflow CLI and airflowctl during the transition, with PR templates and documentation.

What defines this AIP as "done"?

Tooling will decrease the migration effort a lot. Only the part that needs to be considered as a manual step is storing their credentials (username:password ) secure for their automated user and authenticate before executing any command, similar to acquiring the token before calling the API.

What defines this AIP as "done"?

We need to ensure tooling is in place to help users to migrate and show guidelines. We will add clear documentation on what is moving and how the replacement will work. We will call airflowctl from Airflow CLI (Remote Commands) and will stop development on those items defined under AIP-81.

Full Switch: The airflow CLI commands will be redirected to airflowctl commands out of the box. We will keep both command of CLI and CTL, i.e. airflow pools get , airflowctl pools get