User Story

As a developer who authenticates with the GitHub CLI, I want Specify to obtain its GitHub credential from gh automatically so that I do not have to store a token at rest, either in auth.json or in an environment variable.

Background

Specify reads authentication configuration from the user-level ~/.specify/auth.json. It does not read a project-local .specify/auth.json. A provider entry can supply a credential in two ways today:

• token: a static value stored in the file.
• token_env: the name of an environment variable, resolved from the process environment at request time.

token_env avoids a token in the file. For example, GH_TOKEN="$(gh auth token)" specify <command> works today. It still requires the user to export a token into the process environment on every invocation, and users who want no token at rest, including in a shell profile or environment variable, have no automatic option.

Developers who use the GitHub CLI already have a credential managed by gh (OS keychain or gh auth login session). Specify has an azure-cli auth mode that resolves credentials from the Azure CLI on demand. A matching github-cli mode would give GitHub the same behavior and align with the GitHub affinity described in the authentication reference.

The desired configuration:

{
  "providers": [
    {
      "hosts": [
        "github.com",
        "api.github.com",
        "raw.githubusercontent.com",
        "codeload.github.com"
      ],
      "provider": "github",
      "auth": "github-cli"
    }
  ]
}

This replaces the original proposal of general $(command) substitution in token. A dedicated mode runs a fixed command, so configuration cannot cause arbitrary command execution.

Acceptance Criteria

• A provider entry with "auth": "github-cli" is accepted by the auth.json schema and loaded from the user-level ~/.specify/auth.json
• When a credential is needed, Specify runs gh auth token and sends the trimmed stdout as the bearer token
• The command is not run through a shell and is not configurable from auth.json
• The resolved token is cached in memory for the current run, so gh runs at most once per host per run
• The resolved token is not written to disk, logged, or included in error messages
• If gh is not installed, the request fails with a clear error that names the provider and states that the GitHub CLI was not found
• If gh is installed but not authenticated, the request fails with a clear error that suggests gh auth login
• If gh exits non-zero, returns empty output, or exceeds a timeout, the request fails with a clear error that does not include command output
• For GitHub Enterprise hosts, Specify requests the token for the matching host (for example gh auth token --hostname <host>) and has documented behavior when a host is not configured in gh
• Existing auth modes (bearer, azure-cli, token, token_env) behave unchanged, and existing tests pass without modification
• The authentication documentation includes github-cli with the full auth.json example above and the gh auth login prerequisite
• New tests cover: token resolved from gh, per-run caching, gh missing, gh unauthenticated, non-zero exit, empty output, timeout, and token absent from logs and errors

Technical Notes

• Follow the existing azure-cli implementation for mode registration, schema validation, and error handling
• Spawn gh with an argv list and no shell, with a timeout (for example, 10 seconds) and the inherited environment
• Memoize per host per run. This keeps the cost at O(h) subprocess spawns for h distinct hosts, not O(r) for r requests
• Redact the token in all log output and exceptions
• Specify reads only the user-level ~/.specify/auth.json, so no project-level trust handling is needed for this mode

Out of Scope

• General-purpose $(command) substitution in token or any other field
• Reading authentication configuration from a project-local .specify/auth.json
• Credential helpers for tools other than the GitHub CLI
• Persisting the resolved token across runs

Drafted with Claude Code using Claude Sonnet 5.5 in human-supervised interactive mode; issue drafting and revision based on contributor feedback. The author reviewed the content before publishing.