Documentation on the --ui-server command line

[krpatter-intc]

I was trying to determine if I can share a copilot CLI terminal session with another process that is running a python script with the copilot CLI SDK.

The example docs hint at such a feature called the --ui-server command line arg for the TUI+server mode, but its not documented in many places. I cant figure out how to launch the CLI with a specific port number (which I would then want to pass to the SDK using the ExternalServerConfig).

Anyone have more documentation on how to access this feature? or maybe it would not actually work with the use case I described?

[cookesan]

If you only need a stable port for another Python process, use the documented headless server path rather than --ui-server:

copilot --headless --port 4321

Then connect from Python with:

from copilot import CopilotClient, ExternalServerConfig

client = CopilotClient(ExternalServerConfig(url="localhost:4321"))

That matches docs/setup/backend-services.md and the Python README's ExternalServerConfig examples.

--ui-server appears to be a different TUI+server mode. The SDK has foreground-session APIs for that mode, but I could not find a documented way to choose or discover the --ui-server port from the CLI side. So for your described use case, --headless --port is the documented route unless you specifically need to share the live TUI foreground session.

[krpatter-intc]

I was specifically hoping to somehow share the TUI foreground session with the SDK. The idea being I can have the standalone chat OR an integrated terminal chat, and the user can use either depending on the person's preference.

[krpatter-intc]

Thanks at @cookesan that put me on the right path. The --port nor the --headless/--ui-server show up in the copilot --help.

--ui-server --port #

Seems to at least allow for the client to connect (there's some difficulties with how the sharing works that I'll need to work out, but it is at least connecting).

[cookesan]

Nice find; thanks for checking the combined flags.

That makes the docs gap more specific: the SDK exposes foreground-session APIs for TUI+server mode, and the backend docs document --headless --port, but --ui-server --port is not surfaced in help/docs even though it appears to get you a connectable server.

For the sharing behavior, I would look at the foreground-session APIs next: getForegroundSessionId, setForegroundSessionId, and the session.foreground / session.background events. I would still treat the CLI flag combination as undocumented until a maintainer confirms it or the help/docs get updated, but your result is a useful data point.