Skip to content
Ptah Documentation

CLI Agent Not Detected

Ptah can drive several external CLI agents as providers. Each one has to be installed and on the PATH before Ptah will offer it in the provider picker.

Quick check

Section titled “Quick check”

Settings → Providers shows a detection status next to each CLI provider. A green “Detected” badge means Ptah found the binary. A red “Not found” badge means it did not.

Installing the CLIs

Section titled “Installing the CLIs”
ProviderInstall commandBinary name
CopilotFollow the official Copilot CLI instructionscopilot
CodexFollow the official Codex CLI instructionscodex

After installing, fully quit and restart Ptah so it picks up the new PATH.

Common problems

Section titled “Common problems”

Symptom: CLI works in a terminal but Ptah says “Not found.” Likely cause: Ptah inherited the PATH from your desktop session, not from your shell’s rc file. Fix: On macOS/Linux, add the install location to your login environment (e.g. ~/.zprofile or ~/.profile). On Windows, add it to System Properties → Environment Variables → Path. Then relaunch Ptah.

Symptom: ENOENT: spawn copilot on Windows, even though copilot --version works in a terminal. Likely cause: npm-installed CLIs on Windows are .cmd wrapper scripts. Node’s spawn() with shell: false cannot execute .cmd files directly. Fix: Ptah handles this automatically via a shell-execution fallback, but if you’ve customised the CLI install:

  • Make sure the .cmd wrapper is the one on PATH (not a stray .ps1).
  • Verify by running where copilot in PowerShell — the first match should end in .cmd.

Symptom: CLI detected but the first message fails with “authentication required.” Likely cause: The CLI has not completed its own login flow yet. Fix: Open a terminal and run the CLI’s login command once (for example codex login). Return to Ptah; the next request will use the stored credentials.

Symptom: CLI detected but runs with the wrong account. Likely cause: The CLI uses a token file that another tool overwrote. Fix: Re-run the CLI’s login command. Each CLI stores its credentials independently of Ptah.

Forcing a specific binary

Section titled “Forcing a specific binary”

You can override auto-detection by setting an absolute path in ~/.ptah/settings.json:

{
  "providers": {
    "codex": { "executablePath": "/opt/homebrew/bin/codex" }
  }
}

This skips PATH lookup entirely and is useful when multiple versions are installed side-by-side.