{"record":{"id":"929a96fe9f03b67e","repo":"openai/codex","slug":"remote-auth-token-env-is-only-supported-for-in","errorCode":null,"errorMessage":"`--remote-auth-token-env` is only supported for interactive TUI commands, not `codex {subcommand}`","messagePattern":"`--remote-auth-token-env` is only supported for interactive TUI commands, not `codex (.+?)`","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"codex-rs/cli/src/main.rs","lineNumber":2376,"sourceCode":"fn prepend_config_flags(\n    subcommand_config_overrides: &mut CliConfigOverrides,\n    cli_config_overrides: CliConfigOverrides,\n) {\n    subcommand_config_overrides.prepend_root_overrides(cli_config_overrides);\n}\n\nfn reject_remote_mode_for_subcommand(\n    remote: Option<&str>,\n    remote_auth_token_env: Option<&str>,\n    subcommand: &str,\n) -> anyhow::Result<()> {\n    if let Some(remote) = remote {\n        anyhow::bail!(\n            \"`--remote {remote}` is only supported for interactive TUI commands, not `codex {subcommand}`\"\n        );\n    }\n    if remote_auth_token_env.is_some() {\n        anyhow::bail!(\n            \"`--remote-auth-token-env` is only supported for interactive TUI commands, not `codex {subcommand}`\"\n        );\n    }\n    Ok(())\n}\n\nfn reject_root_strict_config_for_subcommand(\n    strict_config: bool,\n    subcommand: &Option<Subcommand>,\n) -> anyhow::Result<()> {\n    if !strict_config {\n        return Ok(());\n    }\n\n    match unsupported_subcommand_name_for_strict_config(subcommand) {\n        Some(subcommand_name) => {\n            reject_strict_config_for_unsupported_subcommand(strict_config, subcommand_name)\n        }","sourceCodeStart":2358,"sourceCodeEnd":2394,"githubUrl":"https://github.com/openai/codex/blob/339751715c64496cb86246bfb3935f40e309dd3d/codex-rs/cli/src/main.rs#L2358-L2394","documentation":"The codex CLI supports remote mode (--remote and --remote-auth-token-env) only on interactive TUI commands. After clap parses the root flags, reject_remote_mode_for_subcommand (called directly and via reject_remote_mode_for_app_server_subcommand) bails when a non-TUI invocation carries --remote-auth-token-env, because only the interactive TUI path (run_interactive_tui) reads that variable to authenticate to a remote exec server. The {subcommand} placeholder names the exact command you ran, e.g. `app-server` or `app-server daemon start`.","triggerScenarios":"Invoking any non-TUI command wired to the remote-mode reject guards with the flag set, e.g. `codex app-server --remote-auth-token-env CODEX_TOKEN` or `codex app-server daemon start --remote-auth-token-env CODEX_TOKEN`. The sibling check one line earlier bails the same way for `--remote <addr>`.","commonSituations":"Copying a working TUI invocation (`codex --remote wss://host --remote-auth-token-env CODEX_TOKEN`) into a systemd unit, Docker entrypoint, or wrapper script that runs `codex app-server`; aliases or argv arrays that attach remote flags to every codex call; upgrading to a codex version where these flags became TUI-only.","solutions":["Remove `--remote-auth-token-env` (and `--remote`) from the non-TUI subcommand; the app-server path never reads them.","Run the interactive TUI when you want remote mode: `codex --remote <addr> --remote-auth-token-env <VAR>`.","For headless remote usage, drive the app-server/exec-server JSON-RPC surface and authenticate at that layer instead of TUI remote flags.","Confirm accepted flags per command with `codex <subcommand> --help` before scripting."],"exampleFix":"# before\ncodex app-server daemon start --remote-auth-token-env CODEX_REMOTE_TOKEN\n# after\ncodex app-server daemon start\n\n# remote flags belong to the interactive TUI:\ncodex --remote wss://exec.example.com --remote-auth-token-env CODEX_REMOTE_TOKEN","handlingStrategy":"validation","validationCode":"#!/usr/bin/env bash\n# run-codex.sh -- refuse TUI-only flags on non-TUI subcommands\nsub=\"${1:-}\"; [ $# -gt 0 ] && shift\ncase \"$sub\" in\n  \"\"|tui) exec codex ${sub:+\"$sub\"} \"$@\" ;;\n  *)\n    for a in \"$@\"; do\n      case \"$a\" in\n        --remote|--remote-auth-token-env*)\n          echo \"refusing: '$a' is TUI-only, not valid for 'codex $sub'\" >&2; exit 2 ;;\n      esac\n    done\n    exec codex \"$sub\" \"$@\" ;;\nesac","typeGuard":null,"tryCatchPattern":"if ! codex app-server daemon start --remote-auth-token-env CODEX_TOKEN 2>err.log; then\n  if grep -q 'only supported for interactive TUI commands' err.log; then\n    echo \"remote flags are TUI-only; retrying without them\" >&2\n    exec codex app-server daemon start\n  fi\n  exit 1\nfi","preventionTips":["Keep TUI-only flags in a dedicated variable used only for interactive invocations","Validate the flag set against `codex <subcommand> --help` inside wrapper scripts","Re-check flag support after codex upgrades; remote flags have moved before"],"tags":["cli","codex","flag-validation","remote","tui"],"backgroundTag":"unsupported-cli-flag","analyzedSha":"339751715c64496cb86246bfb3935f40e309dd3d","analyzedAt":"2026-08-25T05:35:09.876Z","schemaVersion":2},"datasetVersion":"2026-08-25T06:17:31.827Z"}