fix(cli): a project .env key is used only when nothing is saved (#7848)

A HEYGEN_API_KEY or HYPERFRAMES_API_KEY that a project .env sets now comes
after every credential the person saved or exported. The CLI resolver, the
media environment and the media-use skill use it only when there is no saved
login, no saved API key and no key in the shell. When one is used, a single
stderr line names the .env file.

An expired, foreign-client, unreadable or refused login now raises the login
error instead of switching to a project .env key, whether or not the folder
has a received-files record. A key exported in the shell, or set by the app
that launched the CLI, keeps its current place, and the host gateway path is
unchanged.
This commit is contained in:
Michael Wang
2026-11-15 17:59:08 +00:00
committed by GitHub
parent 96cc8cb852
commit de1ce68988
14 changed files with 265 additions and 295 deletions
+4 -2
View File
@@ -37,7 +37,7 @@ Signing in is the same OAuth step as creating an account — new users land on t
</Step>
</Steps>
HyperFrames uses its own public OAuth client and stores credentials in `~/.hyperframes/credentials` (mode `0600`). Sign in again after upgrading from the shared HeyGen login. The separate [`heygen` CLI](https://github.com/heygen-com/heygen-cli) keeps its own login in `~/.heygen`; HyperFrames does not move or delete it. A signed-in HyperFrames session wins over `HEYGEN_API_KEY` in the environment. The environment key is used only when no session is signed in, when HeyGen refuses to refresh the session, or when a host app routes calls through its own gateway. An expired session never selects a saved API key instead. An API key, from the environment or `auth login --api-key`, selects API-key billing.
HyperFrames uses its own public OAuth client and stores credentials in `~/.hyperframes/credentials` (mode `0600`). Sign in again after upgrading from the shared HeyGen login. The separate [`heygen` CLI](https://github.com/heygen-com/heygen-cli) keeps its own login in `~/.heygen`; HyperFrames does not move or delete it. A signed-in HyperFrames session wins over `HEYGEN_API_KEY` in the environment. The environment key is used only when no session is signed in, when HeyGen refuses to refresh the session, or when a host app routes calls through its own gateway. An expired session never selects a saved API key instead. A key from the project `.env` is used only when no session or API key is saved and the environment sets none, and the CLI names that `.env` file on stderr when it uses one. An API key, from the environment or `auth login --api-key`, selects API-key billing.
`auth status` verifies identity. For a dedicated HyperFrames OAuth login it reports the billing product, but the HyperFrames balance is unavailable here: `/v3/users/me` returns generic HeyGen account billing fields. Those raw fields remain in JSON and are not presented as the HyperFrames balance. Host-injected or custom-client OAuth is reported as an unverified billing product.
@@ -58,8 +58,10 @@ sound retrieval. It resolves first-match-wins:
4. `HEYGEN_API_KEY` — environment variable
5. `HYPERFRAMES_API_KEY` — alias, for parity with other tools
6. An API key saved in `~/.hyperframes/credentials` by `hyperframes auth login --api-key`
7. A key from a nearby project `.env`, only when nothing is saved
A nearby project `.env` can supply the keys, but never `HEYGEN_API_BASE`. Point at a different config directory
A nearby project `.env` can supply the keys, but never `HEYGEN_API_BASE`. Its key never replaces a saved
session or API key, including an expired session, and the scripts name the `.env` file on stderr when they use it. Point at a different config directory
with `HYPERFRAMES_CONFIG_DIR`. The scripts can't refresh a session; the `hyperframes` CLI's own commands use the same
order and refresh an expired session first. See the [CLI reference](/packages/cli). When `media-use` invokes the separate `heygen` executable, it supplies an isolated temporary credential containing the selected access token. That helper cannot refresh a HyperFrames grant or pick up another HeyGen login.
+8 -3
View File
@@ -116,7 +116,8 @@ Some commands add their own fields next to `error`, such as `findings` from
**The project `.env`.** The `.env` in the current directory sets only the CLI's own
settings: `HEYGEN_API_KEY`, `HYPERFRAMES_API_KEY`, `ELEVENLABS_API_KEY`, `FIGMA_TOKEN`, and the
vision keys, models, Vertex settings and timeout, and the telemetry opt-outs `HYPERFRAMES_NO_TELEMETRY` and `DO_NOT_TRACK`. A variable already in your environment wins. Any
other key in the file is ignored, and one line on stderr names them.
other key in the file is ignored, and one line on stderr names them. A HeyGen key from the `.env` is used only
when no login or API key is saved (see [`auth`](#hyperframes-auth)).
**Flags, not prompts.** A missing required flag fails immediately with a usage
example rather than waiting for input. These commands can ask questions on a TTY:
@@ -2586,9 +2587,13 @@ First match wins:
1. `HEYGEN_ACCESS_TOKEN` (an OAuth token a host app injects; never refreshed or saved)
2. Your `hyperframes auth login` session in `~/.hyperframes/credentials`. An expired session is refreshed first.
3. `HEYGEN_API_KEY`
3. `HEYGEN_API_KEY` set in your environment
4. `HYPERFRAMES_API_KEY` (a HyperFrames alias for the same thing)
5. An API key saved with `hyperframes auth login --api-key`
6. A `HEYGEN_API_KEY` or `HYPERFRAMES_API_KEY` from the project `.env`, only when nothing is saved
A project `.env` key never replaces an expired session or a saved key. When the CLI
uses one, it prints a line on stderr that names the `.env` file.
A signed-in session wins over an API key in the environment. The environment key
is used instead when HeyGen refuses to refresh the session, or when `HEYGEN_API_URL` or
@@ -2655,7 +2660,7 @@ hyperframes auth logout --yes # no prompt
| Variable | Description |
| --------------------- | ------------------------------------------------ |
| `HEYGEN_API_KEY` | API key, used when no session is signed in. Wins over a key saved with `--api-key`. |
| `HEYGEN_API_KEY` | API key, used when no session is signed in. Wins over a key saved with `--api-key`. A project `.env` key is used only when nothing is saved. |
| `HYPERFRAMES_API_KEY` | Alias for `HEYGEN_API_KEY`. |
| `HEYGEN_ACCESS_TOKEN` | OAuth token from a host app; used first, never refreshed. |
| `HEYGEN_API_URL` | API base URL (default `https://api.heygen.com`). |