refactor(consume): avoid github api calls for direct url fixture inputs (ethereum#1788)

* feat(consume): add `--no-api-calls` flag for --input=<github-release-url>

* docs(consume): update consume cache docs for the `--no-api-calls` flag

* docs(hive): align sub-section title style

* docs: update changelog

* Apply suggestions from code review

Co-authored-by: spencer <[email protected]>

* refactor(consume): simplify API behavior for direct URLs

Remove the --no-api-calls flag and instead make the behavior automatic:
- Direct GitHub release URLs: No API calls, no release page output
- Release specifiers (stable@latest): API calls required, includes release page

This provides better CI/UX without requiring additional flags.

* docs(changelog): update consume API behavior entry

Describe the automatic API call avoidance for direct URLs without
mentioning any flags since we implemented automatic behavior.

* Apply suggestions from code review

Co-authored-by: spencer <[email protected]>

---------

Co-authored-by: spencer <[email protected]>

Author: danceratopz

CHANGELOG.md

@@ -41,6 +41,8 @@ Users can select any of the artifacts depending on their testing needs for their
 
 #### `consume`
 
+- 🔀 `consume` now automatically avoids GitHub API calls when using direct release URLs (better for CI environments), while release specifiers like `stable@latest` continue to use the API for version resolution ([#1788](https://github.com/ethereum/execution-spec-tests/pull/1788)).
+
 #### `execute`
 
 - ✨ Add `blob_transaction_test` execute test spec, which allows tests that send blob transactions to a running client and verifying its `engine_getBlobsVX` endpoint behavior ([#1644](https://github.com/ethereum/execution-spec-tests/pull/1644)).

running_tests/consume/cache.md

@@ -39,6 +39,8 @@ Releases can be downloaded using EEST tooling without (manually) cloning and ins
     Release page: https://github.com/ethereum/execution-spec-tests/releases/tag/v4.5.0
     ```
 
+    **Note:** Use direct URLs to avoid GitHub API calls (better for CI environments). Version specifiers like `stable@latest` will always use the GitHub API to resolve versions. More details on the arguments to `--input` are provided below.
+
     **Explanation:** `uv` creates a local Python virtual environment in `~/.cache/uv/`, installs EEST and executes the `consume cache` command to resolve and download the release, which gets cached at `~/.cache/ethereum-execution-spec-tests`. Subsequent commands will use the cached version of the fixtures.
 
 ## The `--input` Flag to Specify Fixtures
@@ -106,6 +108,12 @@ All remote fixture sources are automatically cached to avoid repeated downloads:
 ~/.cache/ethereum-execution-spec-tests/cached_downloads/
 ```
 
+You can override this location with the `--cache-folder` flag:
+
+```bash
+uv run consume cache --input stable@latest --cache-folder /path/to/custom/cache
+```
+
 **Cache structure:**
 
 ```text
@@ -137,3 +145,26 @@ All remote fixture sources are automatically cached to avoid repeated downloads:
 ## The Fixture Index File
 
 The [`fill` command](../../filling_tests/index.md) generates a JSON file `<fixture_path>/.meta/index.json` that indexes the fixtures its generated. This index file is used by `consume` commands to allow fast collection of test subsets specified on the command-line, for example, via the `--sim.limit` flag. For help with `--sim.limit` when running `./hive`, see [Hive Common Options](../hive/common_options.md), for an overview of other available test selection flags when running `consume` directly, see [Useful Pytest Options](../useful_pytest_options.md).
+
+## CI-Friendly Behavior for Direct URLs
+
+When using direct GitHub release URLs (instead of version specifiers), the consume command automatically avoids unnecessary GitHub API calls to prevent rate limiting in CI environments:
+
+```console
+consume cache --input=https://github.com/ethereum/execution-spec-tests/releases/download/v4.5.0/fixtures_stable.tar.gz
+```
+
+**API Call Behavior:**
+
+- ✅ **Direct URLs**: No API calls made, cleaner output (no "Release page:" line).
+- ℹ️ **Version specifiers**: API calls required to resolve versions, includes release page info.
+
+Examples:
+
+```console
+# No API calls - direct download
+consume cache --input=https://github.com/ethereum/execution-spec-tests/releases/download/v4.5.0/fixtures_stable.tar.gz
+
+# API calls required - version resolution  
+consume cache --input=stable@latest
+```

running_tests/hive/dev_mode.md

@@ -21,7 +21,7 @@ This avoids running the simulator in a dockerized environment and has several ad
 - EEST is installed, see [Installation](../../getting_started/installation.md)
 - Hive is built, see [Hive](../hive/index.md#quick-start).
 
-## Hive Dev Setup (Linux)
+## Hive Dev Setup on Linux
 
 1. Start Hive in development mode, e.g.:
 
@@ -50,7 +50,7 @@ This avoids running the simulator in a dockerized environment and has several ad
     uv run consume rlp --input stable@latest
     ```
 
-## macOS Setup
+## Hive Dev Setup on macOS
 
 Due to Docker running within a VM on macOS, the host machine and Docker containers don't share the same network namespace, preventing direct communication with Hive's development server. To run development mode on macOS, you have the following options: