Frequently asked questions

The tray icon didn't appear after launching

Only one instance of CLIProxyAPI Tray can run at a time. The tray uses a Windows mutex (Global\CLIProxyAPI_Tray_SingleInstance) — if one is already running, any new launch exits silently.Steps to diagnose:

Open Task Manager and look for existing powershell.exe or pwsh.exe processes. If one is running the tray, ending it will let you relaunch.

Run the script directly in a PowerShell window to see any error output:

powershell -STA -NoProfile -ExecutionPolicy Bypass -File "C:\path\to\cli-proxy-api.ps1"

Check your execution policy — it must allow the script to run:
```
Get-ExecutionPolicy -List
```

The WebUI won't open in my browser

The tray checks that the configured port is accepting TCP connections before opening a browser window. If the port check fails, it shows “Not running (port not listening)” instead.Check these things:

Confirm CLIProxyAPI is running — the tray tooltip should say “CLIProxyAPI Tray - Running”
Find your port in config.yaml (default: 8317)
Try opening the URL manually: http://127.0.0.1:8317/management.html
If CLIProxyAPI is running but the page won’t load, check whether Windows Firewall is blocking the port

I keep getting prompted for a password

The password prompt appears whenever secret-key in config.yaml is empty. This usually means the tray couldn’t write the password to config.yaml on a previous attempt.Fix:

Ensure config.yaml exists and is writable by your Windows user
Avoid installing to protected locations like Program Files — use %USERPROFILE%\.cli-proxy-api-tray\ instead
Use Settings → Reset Password to set the password through the tray; it writes directly to config.yaml

The update download failed

Update downloads require access to GitHub Releases (https://github.com/router-for-me/CLIProxyAPI/releases).Check these things:

Verify you can access GitHub from your browser
If you’re on a corporate network, check whether a proxy or firewall is blocking the download
Temporary download files are cleaned up automatically even when a download fails — your existing installed version remains intact
Try again with Update from the tray menu

settings.json won't save (balloon tip about save failure)

If the install directory is not writable, the tray shows a balloon tip and falls back to writing settings.json to %LOCALAPPDATA%\CLIProxyAPI_Tray\settings.json.This is expected behavior. The tray continues working normally using the fallback path. To restore primary behavior, move the install directory to a location your user account can write to.

CLIProxyAPI shows 'port not ready yet' after starting

After launching cli-proxy-api.exe, the tray waits up to 12 seconds for the port to start accepting connections. If the port isn’t ready within that window, you see “Started, but port not ready yet”.This usually means:

CLIProxyAPI is still initializing — wait a moment and try opening the WebUI manually
Another process is already using the port — check with: netstat -an | findstr 8317
CLIProxyAPI encountered an error at startup — check logs/ if logging-to-file: true is set in config.yaml

How do I use PowerShell 7 instead of Windows PowerShell?

The VBS launcher (cli-proxy-api.vbs) automatically detects and prefers pwsh.exe (PowerShell 7) if it is on your %PATH% or installed at %ProgramFiles%\PowerShell\7\pwsh.exe.To force PowerShell 7 when creating the shortcut:

# Re-run installer with explicit shell selection
irm https://raw.githubusercontent.com/kitephp/CLIProxyAPI-Tray/main/install.ps1 | iex -Args "-ShortcutShell PowerShell7"

Or run create-shortcut.bat after installing PowerShell 7 — it will pick up pwsh.exe automatically.

Can I run CLIProxyAPI Tray on Windows Server?

CLIProxyAPI Tray requires a graphical desktop environment because it uses Windows Forms and the system tray notification area. Windows Server with Desktop Experience should work. Windows Server Core (no GUI) does not support the tray.

Get Started

Usage

Configuration

Reference & Troubleshooting

Report an issue

Build docs developers (and LLMs) love