Add `astro api` command by jeremybeard · Pull Request #2006 · astronomer/astro-cli

jeremybeard · 2026-02-05T20:49:29Z

Description

Add the astro api top-level command with two subcommands for making authenticated API requests to Astronomer services:

astro api airflow — make requests to the Airflow REST API (local or deployed), with automatic version detection and OpenAPI spec resolution.

astro api cloud — make requests to the Astro Cloud platform API using the current context's bearer token.

Both subcommands support:

Endpoint discovery via ls and describe (parsed from OpenAPI specs)
Calling endpoints by operation ID or raw path
Pagination (per-page streaming or --slurp into a single array)
jq filters and Go-template output formatting
Colored JSON output
--curl flag to emit equivalent curl commands
Magic field syntax for request bodies (@file, :=json, =string)
Custom headers and path-parameter overrides

Supporting packages:

pkg/openapi: OpenAPI spec fetching, caching, endpoint indexing, Airflow version-range mapping, and schema introspection.

🧪 Functional Testing

Airflow local: Run astro dev start, then astro api airflow ls to list available endpoints. Call an endpoint by operation ID, e.g. astro api airflow get_health.
Airflow deployed: Run astro api airflow -d <deployment-id> ls to list endpoints on a deployed Airflow instance. Call an endpoint, e.g. astro api airflow -d <deployment-id> get_dags.
Cloud API: Run astro api cloud ls to list Astro platform endpoints. Call an endpoint, e.g. astro api cloud list-deployments --path-param organizationId=<org-id>.
Describe: Run astro api airflow describe get_dags or astro api cloud describe list-deployments to see endpoint details including parameters and response schemas.
Output formatting: Test --jq '.dags[]', --template '{{range .dags}}{{.dag_id}}{{end}}', --silent, and --slurp flags.
Curl generation: Add --curl to any request to verify the generated curl command.
Error handling: Call a nonexistent endpoint and verify the CLI exits non-zero with the error body printed.

📋 Checklist

Rebased from the main (or release if patching) branch (before testing)
Ran make test before taking out of draft
Ran make lint before taking out of draft
Added/updated applicable tests
Tested against Astro-API (if necessary).
Tested against Houston-API and Astronomer (if necessary).
Communicated to/tagged owners of respective clients potentially impacted by these changes.
Updated any related documentation

coveralls-official · 2026-02-05T21:10:23Z

Pull Request Test Coverage Report for Build 4cf0f249-3ceb-45e4-8eea-c8b56b786960

Details

2079 of 2468 (84.24%) changed or added relevant lines in 13 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage increased (+1.9%) to 35.078%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
pkg/openapi/schema.go	26	27	96.3%
pkg/openapi/airflow_versions.go	27	29	93.1%
cmd/api/list.go	109	113	96.46%
pkg/openapi/endpoints.go	120	125	96.0%
cmd/api/api.go	37	45	82.22%
cmd/api/fields.go	141	151	93.38%
cmd/api/output.go	114	124	91.94%
pkg/openapi/cache.go	136	155	87.74%
cmd/api/describe.go	355	381	93.18%
cmd/api/request.go	386	439	87.93%

Totals
Change from base Build 63595748-3be8-42e5-8f39-9a30d684e069:	1.9%
Covered Lines:	22944
Relevant Lines:	65409

💛 - Coveralls

Introduce the `astro api` top-level command with two subcommands: astro api airflow — make requests to the Airflow REST API (local or deployed), with automatic version detection (2.x, 3.0.x, 3.0.3+) and OpenAPI spec resolution. astro api cloud — make requests to the Astro Cloud platform API using the current context's bearer token. Both subcommands support: - Endpoint discovery via `ls` and `describe` (parsed from OpenAPI specs) - Calling endpoints by operation ID or raw path - Pagination (per-page streaming or --slurp into a single array) - Response caching with TTL and automatic stale-entry cleanup - jq filters and Go-template output formatting - Colored JSON output - --curl flag to emit equivalent curl commands - Magic field syntax for request bodies (@file, :=json, =string) - Custom headers and path-parameter overrides Supporting packages: - pkg/openapi: OpenAPI spec fetching, caching, endpoint indexing, Airflow version-range mapping, and schema introspection. Includes unit tests for request handling, output formatting, field parsing, OpenAPI version mapping, endpoint indexing, and caching.

Copilot

Pull request overview

Adds the new astro api command group for making authenticated requests to Astro Cloud and Airflow APIs, backed by OpenAPI spec discovery/caching and rich output formatting.

Changes:

Introduces astro api cloud and astro api airflow commands with ls and describe helpers, request execution, pagination, caching, curl generation, and output formatting (jq/templates/color).
Adds pkg/openapi utilities for fetching/caching OpenAPI specs, endpoint extraction/filtering, and Airflow version→spec-path mapping.
Updates dependencies and root command registration + README command list.

Reviewed changes

Copilot reviewed 27 out of 28 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pkg/openapi/types.go	Adds minimal OpenAPI 3.0 struct types + `Endpoint` model for discovery/describe.
pkg/openapi/schema.go	Adds `$ref` resolution utilities for schema introspection in `describe`.
pkg/openapi/schema_test.go	Unit tests for schema resolver behavior.
pkg/openapi/endpoints.go	Implements endpoint extraction/sorting/filtering/path-param extraction.
pkg/openapi/endpoints_test.go	Unit tests for endpoint extraction/filtering/lookup.
pkg/openapi/cache.go	Implements spec fetch + on-disk caching with TTL, plus Airflow per-version cache config.
pkg/openapi/cache_test.go	Unit tests for cache read/write/fetch behavior and prefix stripping.
pkg/openapi/airflow_versions.go	Maps Airflow versions to OpenAPI spec paths + builds raw GitHub URLs.
pkg/openapi/airflow_versions_test.go	Unit tests for version-range mapping + URL building + normalization.
cmd/root.go	Registers the new `api` top-level command.
cmd/api/api.go	Adds `astro api` parent command + `--no-color` flag and subcommands.
cmd/api/cloud.go	Implements `astro api cloud` request flow + placeholder/path-param handling + subcommands.
cmd/api/cloud_test.go	Unit tests for cloud command utilities and spec operation-id resolution.
cmd/api/airflow.go	Implements `astro api airflow` including auth/token/version detection and subcommands.
cmd/api/airflow_test.go	Unit tests for Airflow auth/version detection/spec-cache init and command wiring.
cmd/api/list.go	Implements `ls` endpoint listing (table + verbose) for both APIs.
cmd/api/list_test.go	Unit tests for list rendering/grouping/filtering.
cmd/api/describe.go	Implements `describe` endpoint schema/params rendering using OpenAPI schemas/resolver.
cmd/api/describe_test.go	Unit tests for describe output and schema rendering edge cases.
cmd/api/fields.go	Implements magic/raw field parsing for request bodies with nested/array syntax.
cmd/api/fields_test.go	Unit tests for field parsing and magic conversions/file reads.
cmd/api/output.go	Implements jq filtering, Go templates, and colorized pretty JSON output.
cmd/api/output_test.go	Unit tests for jq/template/colorized JSON output behavior.
cmd/api/request.go	Implements HTTP execution, verbose I/O, pagination, curl generation, and response caching.
cmd/api/request_test.go	Extensive unit tests for request execution, pagination, caching, curl quoting, etc.
go.mod	Adds jq/json coloring deps and bumps several module versions.
README.md	Documents the new `api` command in the CLI command list.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

cmd/api/request.go

pkg/openapi/schema.go

jlaneve · 2026-02-13T22:12:23Z

pkg/openapi/types.go

@@ -0,0 +1,120 @@
+// Package openapi provides utilities for working with OpenAPI specifications.


chatted about this offline but it'd be good to see if we can find a package for this instead of maintaining it ourselves

Switched it to kin-openapi, which was actually already a transitive dependency

jeremybeard changed the title ~~Add astro api command for authenticated Airflow and Cloud API requests~~ Add astro api command Feb 5, 2026

jeremybeard force-pushed the api-command branch from 7868dd1 to dbb3d6a Compare February 5, 2026 21:27

jeremybeard marked this pull request as ready for review February 6, 2026 14:17

jeremybeard requested review from kushalmalani and neel-astro as code owners February 6, 2026 14:17

kaxil requested a review from schnie February 6, 2026 14:35

jeremybeard requested review from a team and removed request for kushalmalani, neel-astro and schnie February 6, 2026 15:45

jlaneve requested a review from Copilot February 7, 2026 19:03

Copilot AI reviewed Feb 7, 2026

View reviewed changes

cmd/api/request.go Show resolved Hide resolved

cmd/api/request.go Outdated Show resolved Hide resolved

cmd/api/request.go Outdated Show resolved Hide resolved

cmd/api/request.go Show resolved Hide resolved

pkg/openapi/schema.go Outdated Show resolved Hide resolved

jeremybeard added 3 commits February 11, 2026 09:53

Feedback updates

3aa9820

Support Astro API for non-prod envs

cddc871

Remove response cache flag

e9293c1

jlaneve reviewed Feb 13, 2026

View reviewed changes

jeremybeard added 4 commits February 13, 2026 21:21

Use kin-openapi for OpenAPI library

61bf2af

Lint

d1b5058

Fix overwriting pre-run logic

8db6544

Lint

fc938c8

jlaneve approved these changes Feb 17, 2026

View reviewed changes

jeremybeard merged commit b1e7f23 into main Feb 17, 2026
5 of 6 checks passed

jeremybeard deleted the api-command branch February 17, 2026 18:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Add `astro api` command#2006

Add `astro api` command#2006
jeremybeard merged 8 commits intomainfrom
api-command

jeremybeard commented Feb 5, 2026 •

edited

Loading

Uh oh!

coveralls-official bot commented Feb 5, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jlaneve Feb 13, 2026

Uh oh!

jeremybeard Feb 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1,120 @@
		// Package openapi provides utilities for working with OpenAPI specifications.

Comments

Conversation

jeremybeard commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

🧪 Functional Testing

📋 Checklist

Uh oh!

coveralls-official bot commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 4cf0f249-3ceb-45e4-8eea-c8b56b786960

Details

💛 - Coveralls

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jlaneve Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

jeremybeard Feb 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jeremybeard commented Feb 5, 2026 •

edited

Loading

coveralls-official bot commented Feb 5, 2026 •

edited

Loading