feat(airflowctl): add task instance management support

[Suraj-kumar00]

Adds Task Instance management support to the airflowctl CLI, enabling users to get, list, clear, and update task instances directly from the terminal.

closes: #61547

Changes

airflow-ctl/src/airflowctl/api/operations.py

• Added TaskInstanceOperations class with get, list, clear, and update methods
• Uses existing auto-generated Pydantic models for request/response validation

airflow-ctl/src/airflowctl/api/client.py

• Added task_instances property to Client, enabling auto-generated CLI commands

airflow-ctl/src/airflowctl/ctl/cli_config.py

• Added "clear" to output_command_list for proper CLI output rendering

airflow-ctl/tests/airflow_ctl/api/test_operations.py

• Added comprehensive TestTaskInstanceOperations test suite with 6 unit tests
• Covers get, list, clear (default and with options), update (state change and note)
• Follows existing XCom test pattern from Add XCom CLI commands to airflowctl #61021

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

• Added integration tests for all 4 taskinstance commands (list, get, clear, update)

New CLI Commands

airflowctl taskinstance list --dag-id <dag_id> --dag-run-id <run_id>
airflowctl taskinstance get --dag-id <dag_id> --dag-run-id <run_id> --task-id <task_id>
airflowctl taskinstance clear --dag-id <dag_id> [--dry-run] [--only-failed] [--task-ids ...]
airflowctl taskinstance update --dag-id <dag_id> --dag-run-id <run_id> --task-id <task_id> [--new-state <state>] [--note <note>]

---

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: Gemini following the guidelines

---

• Read the Pull Request Guidelines for more information. Note: commit author/co-author name and email in commits become permanently public when merged.
• For fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
• When adding dependency, check compliance with the ASF 3rd Party License Policy.
• For significant user-facing changes create newsfragment: {pr_number}.significant.rst or {issue_number}.significant.rst, in airflow-core/newsfragments.

[boring-cyborg]

Congratulations on your first Pull Request and welcome to the Apache Airflow community! If you have any issues or are unsure about any anything please check our Contributors' Guide (https://github.com/apache/airflow/blob/main/contributing-docs/README.rst)
Here are some useful points:

• Pay attention to the quality of your code (ruff, mypy and type annotations). Our prek-hooks will help you with that.
• In case of a new feature add useful documentation (in docstrings or in docs/ directory). Adding a new operator? Check this short guide Consider adding an example DAG that shows how users should use it.
• Consider using Breeze environment for testing locally, it's a heavy docker but it ships with a working Airflow and a lot of integrations.
• Be patient and persistent. It might take some time to get a review or get the final approval from Committers.
• Please follow ASF Code of Conduct for all communication including (but not limited to) comments on Pull Requests, Mailing list and Slack.
• Be sure to read the Airflow Coding style.
• Always keep your Pull Requests rebased, otherwise your build might fail due to changes not related to your commits.
  Apache Airflow is a community-driven project and together we are making it better 🚀.
  In case of doubts contact the developers at:
  Mailing List: dev@airflow.apache.org
  Slack: https://s.apache.org/airflow-slack

[Suraj-kumar00]

Hi @shahar1,

Please review

[bugraoz93]

Thanks for the PR and it looks good! We were going to release new version which delayed a week and some breaking changes needs to be fixes here #61822. Lets hold adding more feature for a couple of days as and decide how to go with schema evolution and we can fit this into new release :)

[Suraj-kumar00]

Thanks for the PR and it looks good! We were going to release new version which delayed a week and some breaking changes needs to be fixes here #61822. Lets hold adding more feature for a couple of days as and decide how to go with schema evolution and we can fit this into new release :)

Sure @bugraoz93, thanks for the update!

Let me know if i can help you with anything from my end.

[dheerajturaga]

Hi @Suraj-kumar00 ! Thanks for contributing and adding the new suite of commands! While @bugraoz93 works on the cleaning up the schema changes, there are few things which would make this PR complete. Would you be able to add unit tests for these commands? I have included an example in the comments which you can use as a reference.

Also, Could you please take a moment to set up and run the static code checks outlined in this document?
https://github.com/apache/airflow/blob/39b914b6775507a5d7420278af5e5eba1272fa24/contributing-docs/08_static_code_checks.rst

Running these locally is highly beneficial because it automatically catches and often fixes formatting issues or simple errors before you push your changes. This saves you from waiting on long CI builds, guarantees your code will pass the automated pipeline, and keeps the code review focused on your actual logic rather than stylistic nitpicks. Let me know if you run into any issues setting it up!

[Suraj-kumar00]

Thanks for the detailed review @dheerajturaga! I've addressed all the feedback:

1. Unit tests — Added comprehensive TestTaskInstanceOperations test suite in test_operations.py with 6 tests covering all operations (get, list, clear, clear_with_options, update, update_with_note), following the XCom tests pattern from Add XCom CLI commands to airflowctl #61021.

2. Integration tests — Added taskinstance clear and taskinstance update integration tests in test_airflowctl_commands.py.

3. clear output command — Added "clear" to output_command_list in cli_config.py.

4. Static code checks — Ran ruff locally; all checks passed.

All 6 unit tests pass locally. Let me know if there's anything else!

[dheerajturaga]

Thanks for the detailed review @dheerajturaga! I've addressed all the feedback:

1. Unit tests — Added comprehensive TestTaskInstanceOperations test suite in test_operations.py with 6 tests covering all operations (get, list, clear, clear_with_options, update, update_with_note), following the XCom tests pattern from Add XCom CLI commands to airflowctl #61021.

2. Integration tests — Added taskinstance clear and taskinstance update integration tests in test_airflowctl_commands.py.

3. clear output command — Added "clear" to output_command_list in cli_config.py.

4. Static code checks — Ran ruff locally; all checks passed.

All 6 unit tests pass locally. Let me know if there's anything else!

Thanks for adding the tests! 😃
I see that the static checks are still failing. Just running ruff isn't enough, you would need to run the prek pre commit checks as mentioned in my earlier comment. Please give it a quick read. It should also automatically update the images for the airflowctl docs.

I also see that the airflowctl checks are failing. Please address them as well

[Suraj-kumar00]

Hi @dheerajturaga,

Please review...

[bugraoz93]

Thanks for the PR! There are still integration tests failing. Could you please check that?

[dheerajturaga]

@Suraj-kumar00 please fix the CI checks?

[potiuk]

@Suraj-kumar00 This PR has been converted to draft because it does not yet meet our Pull Request quality criteria.

Issues found:

• ❌ Other failing CI checks: Failing: Additional PROD image tests / Airflow CTL integration tests with PROD image. Run prek run --from-ref main locally to reproduce. See static checks docs.

Note: Your branch is 606 commits behind main. Some check failures may be caused by changes in the base branch rather than by your PR. Please rebase your branch and push again to get up-to-date CI results.

What to do next:

• The comment informs you what you need to do.
• Fix each issue, then mark the PR as "Ready for review" in the GitHub UI - but only after making sure that all the issues are fixed.
• Maintainers will then proceed with a normal review.

Converting a PR to draft is not a rejection — it is an invitation to bring the PR up to the project's standards so that maintainer review time is spent productively. If you have questions, feel free to ask on the Airflow Slack.

---

Note: This comment was drafted by an AI-assisted triage tool and may contain mistakes. Once you have addressed the points above, an Apache Airflow maintainer — a real person — will take the next look at your PR. We use this two-stage triage process so that our maintainers' limited time is spent where it matters most: the conversation with you.

[Suraj-kumar00]

Hi @potiuk @dheerajturaga,

Could you please approve the PR i believe it needs your approval in-order to run those CI tests, please approve so that i can proceed fixing it.

Thanks

[potiuk]

No. We cannot approve it. FOr some reason your PR gets canceled. I recommend to re-open it, but approval will not change its status. Let me close it now - open a new one @Suraj-kumar00