kelos-dev / kelos-dev/kelos

CLI UX: credential-type flag is misleading for Codex and Gemini agents

Open
#227 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

generated-by-kelos kelos/needs-input kind/feature needs-actor priority/important-longterm triage-accepted
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 key CODEX_API_KEY
  • --credential-type oauth → stores value in secret key CODEX_API_KEY (same!)
For Gemini agent:
  • --credential-type api-key → stores value in secret key GEMINI_API_KEY
  • --credential-type oauth → stores value in secret key GEMINI_API_KEY (same!)
For Claude Code agent (correct behavior):
  • --credential-type api-key → stores value in secret key ANTHROPIC_API_KEY
  • --credential-type oauth → stores value in secret key CLAUDE_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

  1. Users might waste time trying to figure out how to get "OAuth credentials" for Codex/Gemini when they only need an API key
  2. The flag name suggests there's a meaningful choice, but there isn't one for these agents
  3. Users might think they're doing something wrong when both options work the same way
  4. 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 oauth for OAuth tokens, api-key for 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 (reject oauth)
  • For Claude Code: allow both api-key and oauth

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.