Struct ClientOptions 

#[non_exhaustive]
pub struct ClientOptions {

    pub program: CliProgram,
    pub prefix_args: Vec<OsString>,
    pub cwd: PathBuf,
    pub env: Vec<(OsString, OsString)>,
    pub env_remove: Vec<OsString>,
    pub extra_args: Vec<String>,
    pub transport: Transport,
    pub github_token: Option<String>,
    pub use_logged_in_user: Option<bool>,
    pub log_level: Option<LogLevel>,
    pub session_idle_timeout_seconds: Option<u64>,
    pub on_list_models: Option<Arc<dyn ListModelsHandler>>,
    pub session_fs: Option<SessionFsConfig>,
    pub on_get_trace_context: Option<Arc<dyn TraceContextProvider>>,
    pub telemetry: Option<TelemetryConfig>,
    pub copilot_home: Option<PathBuf>,
    pub tcp_connection_token: Option<String>,
    pub remote: bool,
}

Options for starting a Client.

When program is CliProgram::Resolve (the default), Client::start automatically resolves the binary via resolve::copilot_binary() — checking COPILOT_CLI_PATH, the embedded CLI, and then the system PATH and common install locations.

Set program to CliProgram::Path to use an explicit binary.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

program: CliProgram

How to locate the CLI binary.

prefix_args: Vec<OsString>

Arguments prepended before --server (e.g. the script path for node).

cwd: PathBuf

Working directory for the CLI process.

env: Vec<(OsString, OsString)>

Environment variables set on the child process.

env_remove: Vec<OsString>

Environment variable names to remove from the child process.

extra_args: Vec<String>

Extra CLI flags appended after the transport-specific arguments.

transport: Transport

Transport mode used to communicate with the CLI server.

github_token: Option<String>

GitHub token for authentication. When set, the SDK passes the token to the CLI via --auth-token-env COPILOT_SDK_AUTH_TOKEN and exports the token in that env var. When set, the CLI defaults to not using the logged-in user (override with Self::use_logged_in_user).

use_logged_in_user: Option<bool>

Whether the CLI should fall back to the logged-in gh user when no token is provided. None means use the runtime default (true unless Self::github_token is set, in which case false).

log_level: Option<LogLevel>

Log level passed to the CLI server via --log-level. When None, the SDK uses LogLevel::Info.

session_idle_timeout_seconds: Option<u64>

Server-wide idle timeout for sessions, in seconds. When set to a positive value, the SDK passes --session-idle-timeout <secs> to the CLI; sessions without activity for this duration are automatically cleaned up. None or Some(0) leaves sessions running indefinitely (the CLI default).

on_list_models: Option<Arc<dyn ListModelsHandler>>

Optional override for Client::list_models.

When set, Client::list_models returns the handler’s result without making a models.list RPC. This is the BYOK escape hatch for environments where the model catalog is provisioned separately from the GitHub Copilot CLI (e.g. external inference servers selected via Transport::External).

session_fs: Option<SessionFsConfig>

Custom session filesystem provider configuration.

When set, the SDK calls sessionFs.setProvider during Client::start to register a virtualizable filesystem layer with the CLI. Each session created on this client must supply its own SessionFsProvider via SessionConfig::with_session_fs_provider.

on_get_trace_context: Option<Arc<dyn TraceContextProvider>>

Optional TraceContextProvider used to inject W3C Trace Context headers (traceparent / tracestate) on outbound session.create, session.resume, and session.send requests.

When MessageOptions carries a per-turn override (set via MessageOptions::with_trace_context or the underlying fields), it takes precedence over this provider.

telemetry: Option<TelemetryConfig>

OpenTelemetry config forwarded to the spawned CLI process. See TelemetryConfig for the env-var mapping. The SDK takes no OpenTelemetry dependency — this is pure spawn-time env injection.

copilot_home: Option<PathBuf>

Override the directory where the CLI persists its state (sessions, auth, telemetry buffers). When set, exported as COPILOT_HOME to the spawned CLI process. Useful for sandboxing test runs or running multiple isolated SDK instances side-by-side.

tcp_connection_token: Option<String>

Optional connection token for TCP transport. Sent to the CLI in the connect handshake and exported as COPILOT_CONNECTION_TOKEN to spawned CLI processes. Required when the CLI server was started with a token, ignored otherwise.

When the SDK spawns its own CLI in TCP mode and this is left None, a UUID is generated automatically so the loopback listener is safe by default. Combining with Transport::Stdio is invalid and surfaces as an error from Client::start.

remote: bool

Enable remote session support (Mission Control integration). When true, the SDK passes --remote to the spawned CLI process so sessions in a GitHub repository working directory are accessible from GitHub web and mobile. Ignored when connecting to an external server via Transport::External.

Implementations

impl ClientOptions

pub fn new() -> Self

Construct a new ClientOptions with default values.

Equivalent to ClientOptions::default; provided as a documented construction entry point for the builder chain. The struct is #[non_exhaustive], so external callers cannot use struct-literal syntax — use this builder or Default::default plus mut-let.

Example

let opts = ClientOptions::new()
    .with_log_level(LogLevel::Debug)
    .with_github_token("ghp_…");

pub fn with_program(self, program: impl Into<CliProgram>) -> Self

How to locate the CLI binary. See CliProgram.

pub fn with_prefix_args<I, S>(self, args: I) -> Self

where I: IntoIterator<Item = S>, S: Into<OsString>,

Arguments prepended before --server (e.g. the script path for node).

pub fn with_cwd(self, cwd: impl Into<PathBuf>) -> Self

Working directory for the CLI process.

pub fn with_env<I, K, V>(self, env: I) -> Self

where I: IntoIterator<Item = (K, V)>, K: Into<OsString>, V: Into<OsString>,

Environment variables to set on the child process.

pub fn with_env_remove<I, S>(self, names: I) -> Self

where I: IntoIterator<Item = S>, S: Into<OsString>,

Environment variable names to remove from the child process.

pub fn with_extra_args<I, S>(self, args: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Extra CLI flags appended after the transport-specific arguments.

pub fn with_transport(self, transport: Transport) -> Self

Transport mode used to communicate with the CLI server. See Transport.

pub fn with_github_token(self, token: impl Into<String>) -> Self

GitHub token for authentication. The SDK passes the token to the CLI via --auth-token-env COPILOT_SDK_AUTH_TOKEN.

pub fn with_use_logged_in_user(self, use_logged_in: bool) -> Self

Whether the CLI should fall back to the logged-in gh user when no token is provided. See the field docs for default semantics.

pub fn with_log_level(self, level: LogLevel) -> Self

Log level passed to the CLI server via --log-level.

pub fn with_session_idle_timeout_seconds(self, seconds: u64) -> Self

Server-wide idle timeout for sessions (seconds). Pass 0 to leave sessions running indefinitely (the CLI default).

pub fn with_list_models_handler<H>(self, handler: H) -> Self

where H: ListModelsHandler + 'static,

Override Client::list_models with a caller-supplied handler. The handler is wrapped in Arc internally.

pub fn with_session_fs(self, config: SessionFsConfig) -> Self

Custom session filesystem provider configuration.

pub fn with_trace_context_provider<P>(self, provider: P) -> Self

where P: TraceContextProvider + 'static,

Set the TraceContextProvider used to inject W3C Trace Context headers on outbound session.create / session.resume / session.send requests. The provider is wrapped in Arc internally.

pub fn with_telemetry(self, config: TelemetryConfig) -> Self

OpenTelemetry config forwarded to the spawned CLI process.

pub fn with_copilot_home(self, home: impl Into<PathBuf>) -> Self

Override the directory where the CLI persists its state. Set as COPILOT_HOME on the spawned CLI process.

pub fn with_tcp_connection_token(self, token: impl Into<String>) -> Self

Set the connection token for TCP transport. Sent in the connect handshake and exported as COPILOT_CONNECTION_TOKEN to spawned CLI processes.

pub fn with_remote(self, enabled: bool) -> Self

Enable remote session support (Mission Control). Passes --remote to the spawned CLI process.

Trait Implementations

impl Debug for ClientOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ClientOptions

fn default() -> Self

Returns the “default value” for a type.