openai/codex · error

`--remote-auth-token-env` is only supported for interactive

Error message

`--remote-auth-token-env` is only supported for interactive TUI commands, not `codex {subcommand}`

What it means

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`.

Source

Thrown at codex-rs/cli/src/main.rs:2376

fn prepend_config_flags(
    subcommand_config_overrides: &mut CliConfigOverrides,
    cli_config_overrides: CliConfigOverrides,
) {
    subcommand_config_overrides.prepend_root_overrides(cli_config_overrides);
}

fn reject_remote_mode_for_subcommand(
    remote: Option<&str>,
    remote_auth_token_env: Option<&str>,
    subcommand: &str,
) -> anyhow::Result<()> {
    if let Some(remote) = remote {
        anyhow::bail!(
            "`--remote {remote}` is only supported for interactive TUI commands, not `codex {subcommand}`"
        );
    }
    if remote_auth_token_env.is_some() {
        anyhow::bail!(
            "`--remote-auth-token-env` is only supported for interactive TUI commands, not `codex {subcommand}`"
        );
    }
    Ok(())
}

fn reject_root_strict_config_for_subcommand(
    strict_config: bool,
    subcommand: &Option<Subcommand>,
) -> anyhow::Result<()> {
    if !strict_config {
        return Ok(());
    }

    match unsupported_subcommand_name_for_strict_config(subcommand) {
        Some(subcommand_name) => {
            reject_strict_config_for_unsupported_subcommand(strict_config, subcommand_name)
        }

View on GitHub (pinned to 339751715c)

Solutions

1. Remove `--remote-auth-token-env` (and `--remote`) from the non-TUI subcommand; the app-server path never reads them.
2. Run the interactive TUI when you want remote mode: `codex --remote <addr> --remote-auth-token-env <VAR>`.
3. For headless remote usage, drive the app-server/exec-server JSON-RPC surface and authenticate at that layer instead of TUI remote flags.
4. Confirm accepted flags per command with `codex <subcommand> --help` before scripting.

Example fix

# before
codex app-server daemon start --remote-auth-token-env CODEX_REMOTE_TOKEN
# after
codex app-server daemon start

# remote flags belong to the interactive TUI:
codex --remote wss://exec.example.com --remote-auth-token-env CODEX_REMOTE_TOKEN

#!/usr/bin/env bash
# run-codex.sh -- refuse TUI-only flags on non-TUI subcommands
sub="${1:-}"; [ $# -gt 0 ] && shift
case "$sub" in
  ""|tui) exec codex ${sub:+"$sub"} "$@" ;;
  *)
    for a in "$@"; do
      case "$a" in
        --remote|--remote-auth-token-env*)
          echo "refusing: '$a' is TUI-only, not valid for 'codex $sub'" >&2; exit 2 ;;
      esac
    done
    exec codex "$sub" "$@" ;;
esac

if ! codex app-server daemon start --remote-auth-token-env CODEX_TOKEN 2>err.log; then
  if grep -q 'only supported for interactive TUI commands' err.log; then
    echo "remote flags are TUI-only; retrying without them" >&2
    exec codex app-server daemon start
  fi
  exit 1
fi

When it happens

Trigger: 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>`.

Common situations: 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.

Related errors

• `--strict-config` is not supported for `codex {subcommand}`
• environment variable `{env_var_name}` is not set
• environment variable `{env_var_name}` is empty
• failed to load marketplace(s): {issue_lines}
• {} upgrade failure(s) occurred.

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/929a96fe9f03b67e. Report an issue: GitHub.