Sync airflowctl from main to v3-1-test to include all changes in integration tests

airflow-ctl-tests/tests/airflowctl_tests/conftest.py

@@ -235,7 +235,7 @@ def test_commands(login_command, date_param):
     # Define test commands to run with actual running API server
     return [
         login_command,
-        "backfills list",
+        "backfill list",
         "config get --section core --option executor",
         "connections create --connection-id=test_con --conn-type=mysql --password=TEST_PASS -o json",
         "connections list",

airflow-ctl/docs/howto/index.rst

@@ -28,13 +28,24 @@ configuring an airflowctl environment.
 
 
 How to use airflowctl
-----------------------
+---------------------
 
 **Important Note**
 ''''''''''''''''''
 airflowctl needs the Airflow API running to be able to work. Please, see the login section below before use.
 Otherwise, you may get errors.
 
+Datetime Usage
+''''''''''''''
+For datetime parameters, date should be timezone aware and in ISO format.
+For example: ``2025-10-10T10:00:00+00:00``
+Let's take example of triggering a DAG run with a logical date, run after and a note.
+
+.. code-block:: bash
+
+  airflowctl dagrun trigger --dag-id="example_bash_operator" --logical-date="2025-09-06T00:00:00+00:00" --run-after="2025-09-06T00:00:00+00:00" --note="Triggered from airflowctl"
+
+
 Login
 '''''
 airflowctl needs to be able to connect to the Airflow API. You should pass API URL as a parameter to the command
@@ -66,7 +77,39 @@ In both cases token is securely stored in the keyring backend. Only configuratio
 is the API URL and the environment name. The token is stored in the keyring backend and is not persisted in the
 configuration file. The keyring backend is used to securely store the token and is not accessible to the user.
 
+What is authentication for ``airflowctl``?
+``````````````````````````````````````````
+For ``airflowctl`` to be able to communicate with the Airflow API, it needs to authenticate itself and acquire token.
+This is done using either a token or a username and password.
+The token can be acquired from the Airflow API or generated using a username and password.
+
+.. image:: ../images/diagrams/airflowctl_api_network_architecture_diagram.png
+  :target: https://raw.githubusercontent.com/apache/airflow/main/airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.png
+  :width: 100%
+  :alt: airflowctl Auth Login Help
+
+Parameter Details for airflowctl auth login
+```````````````````````````````````````````
+
+**--api-url**: This parameter is required. (e.g. ``http://localhost:8080``)
+The default value is ``http://localhost:8080``. Full URL of the Airflow API. Without any ``/api/*`` suffixes.
+If you are running the ``airflowctl`` in ``breeze`` container, it is optional.
+
+**--api-token**: This parameter is optional.
+If you are setting the token via the environment variable ``AIRFLOW_CLI_TOKEN``, you can skip using this parameter.
+
+**--username**: This parameter is optional.
+If you are not using ``--api-token`` or the environment variable ``AIRFLOW_CLI_TOKEN``, you must provide a username to authentication along with ``--password``.
 
+**--password**: This parameter is optional.
+If you provide a username via ``--username`` this is the required password to authenticate.
+
+**--env**: This parameter is optional.
+The name of the environment to create or update. The default value is ``production``.
+This parameter is useful when you want to manage multiple Airflow environments.
+
+More Usage and Help Pictures
+''''''''''''''''''''''''''''
 For more information use
 
 .. code-block:: bash
@@ -88,7 +131,6 @@ You can use the command ``airflowctl --help`` to see the list of available comma
   :width: 60%
   :alt: airflowctl Help
 
-
 All Available Group Command References
 --------------------------------------
 
@@ -109,10 +151,10 @@ These visual references show the full command syntax, options, and parameters fo
   :width: 60%
   :alt: airflowctl Auth Command
 
-**Backfills**
+**Backfill**
 '''''''''''''
-.. image:: ../images/output_backfills.svg
-  :target: https://raw.githubusercontent.com/apache/airflow/main/airflow-ctl/docs/images/output_backfills.svg
+.. image:: ../images/output_backfill.svg
+  :target: https://raw.githubusercontent.com/apache/airflow/main/airflow-ctl/docs/images/output_backfill.svg
   :width: 60%
   :alt: airflowctl Backfills Command
 
@@ -132,8 +174,8 @@ These visual references show the full command syntax, options, and parameters fo
 
 **Dags**
 ''''''''
-.. image:: ../images/output_dag.svg
-  :target: https://raw.githubusercontent.com/apache/airflow/main/airflow-ctl/docs/images/output_dag.svg
+.. image:: ../images/output_dags.svg
+  :target: https://raw.githubusercontent.com/apache/airflow/main/airflow-ctl/docs/images/output_dags.svg
   :width: 60%
   :alt: airflowctl Dag Command
 

airflow-ctl/docs/images/command_hashes.txt

@@ -1,14 +1,14 @@
-main:8d768c837899829dfd21d37253d2fb44
+main:deacf21c6300eae16afbf8cbd538f1ef
 assets:b3ae2b933e54528bf486ff28e887804d
 auth:f396d4bce90215599dde6ad0a8f30f29
-backfills:725109470cd2613de8cc8af022fb54bc
+backfill:bbce9859a2d1ce054ad22db92dea8c05
 config:cb175bedf29e8a2c2c6a2ebd13d770a7
 connections:a16225e1c7d28488d0da612752669b4b
-dag:0c06fff60c0cc6618c8de05915506605
+dags:6928d0192e95fde5b0c092e0ea5a0703
 dagrun:ec1b6098822419967e621687bd7e5e4b
 jobs:7f8680afff230eb9940bc7fca727bd52
 pools:03fc7d948cbecf16ff8d640eb8f0ce43
 providers:1c0afb2dff31d93ab2934b032a2250ab
 variables:0b04188937b3c364204ef4cc9a541c62
-version:000176f03a175890b12181c8569e2d0f
+version:d4a7a6229b3a204f114283b62eac789b
 auth login:5277c653ff6dce51f37472dc0bda9775

airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.md5sum

@@ -0,0 +1 @@
+ea755b0b93dd0524e7ed0ef42b83a888

airflow-ctl/docs/images/diagrams/airflowctl_api_network_architecture_diagram.py

@@ -0,0 +1,86 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+from __future__ import annotations
+
+from pathlib import Path
+
+from diagrams import Cluster, Diagram, Edge
+from diagrams.onprem.client import User
+from diagrams.onprem.compute import Server
+from rich.console import Console
+
+MY_DIR = Path(__file__).parent
+MY_FILENAME = Path(__file__).with_suffix("").name
+
+console = Console(width=400, color_system="standard")
+
+graph_attr = {
+    "concentrate": "false",
+    "splines": "splines",
+}
+
+edge_attr = {
+    "minlen": "1",
+}
+
+
+def generate_airflowctl_api_network_diagram():
+    image_file = (MY_DIR / MY_FILENAME).with_suffix(".png")
+
+    console.print(f"[bright_blue]Generating network diagram {image_file}")
+    with Diagram(
+        name="airflowctl<->API Network Diagram",
+        show=False,
+        direction="LR",
+        filename=MY_FILENAME,
+        edge_attr=edge_attr,
+        graph_attr=graph_attr,
+    ):
+        # Machine network with client
+        with Cluster("Machine Network", graph_attr={"margin": "30", "width": "10"}):
+            client = User("Client\n(The machine/host has the airflowctl installed)")
+
+        # Airflow deployment network with API server
+        with Cluster("Apache Airflow Deployment Network", graph_attr={"margin": "30"}):
+            api_server = Server("Apache Airflow API Server\n(e.g. DNS: https://airflow.internal.api.com)")
+
+        # Edges representing the flows
+        (
+            client
+            >> Edge(
+                color="blue",
+                style="solid",
+                label="Login Request\n(if not manually used in --api-token or env var. Authentication done with username/password)",
+            )
+            >> api_server
+        )
+
+        (
+            api_server
+            >> Edge(
+                color="darkgreen",
+                style="solid",
+                label="Returns Token",
+            )
+            >> client
+        )
+
+    console.print(f"[green]Generated network diagram {image_file}")
+
+
+if __name__ == "__main__":
+    generate_airflowctl_api_network_diagram()