Skip to main content

CLI Troubleshooting

Return to CLI Installation. Review CLI Versions if you need to verify the latest published release.

Quick lookup

Find your issue in seconds

Search by symptom, status code, command, or keyword. Select a result to jump to the full troubleshooting steps.

Filter by type
8 known issues indexed

Issue Directory​

CategoryTypical issues
InstallationCommand resolution, Python/pip mismatch, execution policy
AuthenticationCallback failures, proxy/TLS trust chain problems
RuntimeVersion drift, dependency install gaps, transient API errors

Command not found after install​

Category: Installation | Difficulty: Low | Time: 2-5 min

Symptom​

phoenix --version returns command not found, 'phoenix' is not recognized, or your shell cannot locate the executable after install completes.

Likely cause​

The installer finished, but the CLI binary directory is not on PATH, or your current shell session has not reloaded updated environment variables.

Fix steps​

  • Windows PowerShell: run Get-Command phoenix -All and echo $env:Path to verify command resolution.
  • Windows PowerShell: close and reopen PowerShell. If needed, append the installer-reported binary directory to your user Path.
  • macOS/Linux: run command -v phoenix, echo $PATH, and reload shell state with exec $SHELL -l.
  • macOS/Linux: if you installed to a custom directory, add it to .zshrc, .bashrc, or .profile.

Verify success​

Run phoenix --version in a new shell and confirm it matches the latest published version on CLI Installation.

When to escalate​

Escalate if the installer reports success but the binary is missing from disk or still unresolved after opening a fresh shell.

Python and pip resolve to different environments​

Category: Installation | Difficulty: Low | Time: 3-5 min

Symptom​

Install commands succeed for one interpreter, but phoenix later fails with missing modules, missing scripts, or an unexpected Python environment.

Likely cause​

python, python3, pip, and pip3 may point to different runtimes. This is common on machines with Homebrew, Microsoft Store Python, pyenv, or multiple virtual environments.

Fix steps​

  • Windows PowerShell: run py --version, py -m pip --version, and Get-Command python,pip,py.
  • Windows PowerShell: prefer py -m pip ... so pip and py use the same interpreter.
  • macOS/Linux: run python3 --version, python3 -m pip --version, and which python3 pip3.
  • macOS/Linux: prefer python3 -m pip ... over plain pip while diagnosing.
  • All platforms: deactivate unexpected virtual environments and rerun install from a clean shell.

Verify success​

The Python executable and pip executable resolve to the same runtime, and phoenix --version works without module import errors.

When to escalate​

Escalate if install still fails even when python -m pip and the interpreter clearly match.

Permission denied or PowerShell execution policy blocks the installer​

Category: Installation | Difficulty: Medium | Time: 5-10 min

Symptom​

The installer exits with Permission denied, Access is denied, cannot execute binary file, or PowerShell reports scripts are disabled.

Likely cause​

The shell lacks execute permission for the downloaded script, or host policy blocks unsigned script execution.

Fix steps​

  • Windows PowerShell: run Get-ExecutionPolicy -List in a regular user shell.
  • Windows PowerShell: use the documented install command with -ExecutionPolicy Bypass for the current process only.
  • macOS/Linux: ensure the download target directory is writable by your user.
  • macOS/Linux: if running a local script, run chmod +x <script-name> first.
  • All platforms: avoid sudo unless system-wide install is explicitly required.

Verify success​

Installer completes without policy/permission errors, and phoenix --version runs in a standard user shell.

When to escalate​

Escalate if endpoint management policy still blocks execution after using the documented per-process bypass.

Browser login callback fails or the CLI cannot complete authentication​

Category: Authentication | Difficulty: Medium | Time: 5-15 min

Symptom​

phoenix login opens a browser, but callback never completes, page hangs, or browser reports a blocked loopback/network callback.

Likely cause​

Loopback callback traffic is blocked by local firewall rules, stale auth state, browser extensions, or proxy interference.

Fix steps​

  • Windows PowerShell: verify http://localhost:<port>/callback is reachable and local firewall rules do not block loopback callback traffic.
  • macOS/Linux: verify local firewall or endpoint security is not blocking loopback access to localhost.
  • All platforms: retry in a clean browser window and temporarily disable privacy/network extensions for the marketplace host.
  • All platforms: set ODCX_CLI_CALLBACK_HOST only if your browser and CLI run in different network namespaces.
  • All platforms: when failures persist, capture browser console + network errors before retrying.

Verify success​

Browser reaches callback URL, CLI prints successful login, and subsequent commands do not request reauthentication.

When to escalate​

Escalate if callback fails consistently across browsers or if corporate controls block local loopback traffic.

Proxy, TLS, or certificate trust failures​

Category: Authentication | Difficulty: High | Time: 10-20 min

Symptom​

Installer or CLI reports TLS handshake failures, certificate verification errors, proxy authentication issues, or inability to reach marketplace APIs.

Likely cause​

Environment requires outbound proxy, uses enterprise TLS interception certificates, or blocks direct access to marketplace/release endpoints.

Fix steps​

  • Windows PowerShell: run Get-ChildItem Env:HTTP_PROXY,HTTPS_PROXY,NO_PROXY and verify enterprise root cert trust.
  • macOS/Linux: run env | grep -E 'HTTP_PROXY|HTTPS_PROXY|NO_PROXY' and verify corporate CA trust in system store.
  • All platforms: verify the marketplace web app and release endpoints are reachable from the same machine.
  • All platforms: if proxy requires auth, configure standard proxy variables before rerunning install/login.

Verify success​

Marketplace API is reachable without certificate warnings, and install/login flows complete without TLS/proxy errors.

When to escalate​

Escalate if corporate proxy certificates cannot be trusted locally, or only ODCX endpoints fail while other HTTPS traffic works.

CLI version mismatch or outdated behavior​

Category: Runtime | Difficulty: Low | Time: 2-5 min

Symptom​

CLI behavior differs from docs, fixed bugs still reproduce, or reported version is older than latest published release.

Likely cause​

Older binaries shadow newer ones on PATH, or host never switched to the newest release.

Fix steps​

  • All platforms: compare phoenix --version against CLI Installation and CLI Versions.
  • Windows PowerShell: run Get-Command phoenix -All to identify duplicate binaries.
  • macOS/Linux: run which -a phoenix to identify duplicate binaries.
  • All platforms: remove/de-prioritize older paths, then reinstall latest release.

Verify success​

phoenix --version resolves to the expected binary path and matches the intended release.

When to escalate​

Escalate if the newest release installs cleanly but still reproduces behavior marked fixed in release notes.

Agent or dependency installation fails​

Category: Runtime | Difficulty: Medium | Time: 5-15 min

Symptom​

odcx install <agent> or phoenix install <agent> partially completes, but required dependencies are missing.

Likely cause​

Marketplace API cannot resolve dependent skills, local install target is partially written, or interrupted installs left inconsistent state.

Fix steps​

  • All platforms: rerun install once to rule out transient fetch failures.
  • All platforms: identify the first failing dependency and whether failure occurred at download, extraction, or registration.
  • Windows PowerShell: verify endpoint security has not quarantined extracted files.
  • macOS/Linux: verify install directory is writable and not mounted read-only.
  • All platforms: use no-dependency flows only for debugging after base install path is validated.

Verify success​

Install completes without warnings, dependencies exist locally, and agent runs without missing-component errors.

When to escalate​

Escalate if the same dependency repeatedly fails on a clean host or marketplace metadata references missing dependency slugs.

Transient 429, 5xx, or timeout errors​

Category: Runtime | Difficulty: Low | Time: 1-3 min

Symptom​

CLI returns 429, 500, 502, 503, 504, or timeout errors while browsing, downloading, or recording installs.

Likely cause​

Marketplace service or upstream proxy is rate-limiting, restarting, or temporarily unavailable.

Fix steps​

  • All platforms: retry command once after a short pause.
  • All platforms: for 429, reduce repeated polling/retries in scripts.
  • All platforms: check marketplace web UI/download page to confirm whether outage is broad.
  • All platforms: rerun with debug logging and keep the first failing timestamp.

Verify success​

Retry succeeds and command completes without additional server errors.

When to escalate​

Escalate immediately if 5xx errors persist across retries, affect multiple users, or block install/login for more than a few minutes.

Still stuck?​

Need faster escalation?

Before opening a ticket, collect the diagnostics below and include links to CLI Installation and CLI Versions in your report so support can quickly verify environment and expected behavior.

Collect diagnostics before opening a ticket​

  • CLI version: phoenix --version
  • Binary resolution:
    • Windows: Get-Command phoenix -All
    • macOS/Linux: which -a phoenix
  • Python and pip resolution:
    • Windows: py --version, py -m pip --version
    • macOS/Linux: python3 --version, python3 -m pip --version
  • Network reachability: verify marketplace UI, download page, and releases API from the affected host.
  • Proxy configuration: capture HTTP_PROXY, HTTPS_PROXY, and NO_PROXY values when applicable.
  • Logs and screenshots: include exact command, timestamp, terminal output, and browser/network errors.
  • Redaction guidance: remove tokens, cookies, personal email addresses, and internal hostnames unless support explicitly requests them.

Escalation​

When filing an issue or escalating to marketplace engineering, include:

  • Exact command that failed and full error text.
  • OS, shell, and whether the host is behind VPN/proxy/VDI/devcontainer.
  • CLI version, resolved binary path, and duplicate binary locations (if any).
  • Timestamps, screenshots, browser console output, and sanitized logs.
  • Whether failure reproduces on a second machine or account.

File product issues through your team's normal ODCX support/engineering intake channel and reference the affected release from CLI Versions.