CLI UX: credential-type flag is misleading for Codex and Gemini agents
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 331
- Forks
- 40
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 70
Description
Problem
The --credential-type flag accepts both api-key and oauth values for all agent types, but for Codex and Gemini agents, both credential types are functionally identical and store the same API key. This is confusing for users who might think they need different types of credentials.
Current Behavior
For Codex agent:
--credential-type api-key→ stores value in secret keyCODEX_API_KEY--credential-type oauth→ stores value in secret keyCODEX_API_KEY(same!)
For Gemini agent:
--credential-type api-key→ stores value in secret keyGEMINI_API_KEY--credential-type oauth→ stores value in secret keyGEMINI_API_KEY(same!)
For Claude Code agent (correct behavior):
--credential-type api-key→ stores value in secret keyANTHROPIC_API_KEY--credential-type oauth→ stores value in secret keyCLAUDE_CODE_OAUTH_TOKEN(different!)
Evidence
internal/cli/run.go:238-262:
func apiKeySecretKey(agentType string) string {
switch agentType {
case "codex":
return "CODEX_API_KEY"
case "gemini":
return "GEMINI_API_KEY"
default:
return "ANTHROPIC_API_KEY"
}
}
func oauthSecretKey(agentType string) string {
switch agentType {
case "codex":
return "CODEX_API_KEY" // <-- Same as apiKeySecretKey!
case "gemini":
return "GEMINI_API_KEY" // <-- Same as apiKeySecretKey!
default:
return "CLAUDE_CODE_OAUTH_TOKEN"
}
}
internal/controller/job_builder.go:86-112: (same pattern)
Why This is Confusing
- Users might waste time trying to figure out how to get "OAuth credentials" for Codex/Gemini when they only need an API key
- The flag name suggests there's a meaningful choice, but there isn't one for these agents
- Users might think they're doing something wrong when both options work the same way
- It's inconsistent with Claude Code where the distinction is meaningful
Impact
- Severity: Medium - doesn't break functionality but creates confusion
- User Impact: New users trying Codex or Gemini agents
- Workaround: Either credential type works fine, but users don't know this
Suggested Solutions
Option 1: Document the behavior (minimal change)
Add a note to CLI help and README that:
- For Claude Code: use
oauthfor OAuth tokens,api-keyfor API keys - For Codex/Gemini: both values work identically; use whichever you prefer
Option 2: Validation (better UX)
Add validation in the CLI that:
- For Codex/Gemini: always use
api-key(rejectoauth) - For Claude Code: allow both
api-keyandoauth
This makes the behavior explicit and prevents confusion.
Option 3: Remove credential-type for non-Claude agents (best but more work)
For Codex/Gemini, remove the credential-type concept entirely:
- Always use API keys (single credential type)
- Only Claude Code needs the credential-type distinction
- Update API validation to reject oauth credential type for Codex/Gemini
Related Issues
- #201: General OAuth vs API key confusion
- #182: Missing client-side validation for enum flags
This issue is more specific: the credential-type distinction is literally meaningless (not just confusing) for 2 out of 3 agent types.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with internal/cli/run.go, especially apiKeySecretKey and oauthSecretKey, then compare the corresponding logic in internal/controller/job_builder.go. Decide which of the documented solutions is intended, and verify that the selected behavior is consistent for Codex, Gemini, and Claude Code across CLI help, validation, and credential storage.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- backend, cli
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100