Struct ClientOptions 

#[non_exhaustive]
pub struct ClientOptions {

    pub program: CliProgram,
    pub prefix_args: Vec<OsString>,
    pub working_directory: 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 base_directory: Option<PathBuf>,
    pub enable_remote_sessions: bool,
    pub bundled_cli_extract_dir: Option<PathBuf>,
    pub mode: ClientMode,
}

Options for starting a Client.

When program is CliProgram::Resolve (the default), Client::start uses COPILOT_CLI_PATH when set to a real file. Otherwise it uses the bundled Copilot CLI when the default bundled-cli cargo feature is enabled, or the build-time extracted dev-cache CLI when that feature is disabled.

Set program to CliProgram::Path to use an explicit binary instead. This skips auto-resolution entirely.

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).

working_directory: 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 does not pass --log-level to the runtime at all and the CLI uses its built-in default.

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.

base_directory: 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.

enable_remote_sessions: 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.

bundled_cli_extract_dir: Option<PathBuf>

Override the directory where the bundled CLI binary is extracted on first use.

When None (the default), the SDK extracts the embedded CLI to <platform cache dir>/github-copilot-sdk/cli/<version>/copilot[.exe], where the cache dir is dirs::cache_dir() — %LOCALAPPDATA% on Windows, ~/Library/Caches/ on macOS, $XDG_CACHE_HOME (or ~/.cache/) on Linux. Use this knob to redirect the extraction (e.g. to a session-scoped temp directory in CI runners) without changing the global cache layout.

Only applies when the bundled-cli cargo feature is on (the default). With bundled-cli disabled (default-features = false) there is no archive to re-extract at runtime — the binary lives at a build-time-known conventional path. To relocate that extraction, set COPILOT_CLI_EXTRACT_DIR (honored symmetrically at build and runtime); to point the runtime at a different binary altogether, use CliProgram::Path or COPILOT_CLI_PATH.

mode: ClientMode

SDK-level mode controlling whether sessions get CLI-style defaults (the default) or are stripped to a minimal/safe baseline. See ClientMode for the contract and trade-offs.

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_base_directory(self, dir: 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_enable_remote_sessions(self, enabled: bool) -> Self

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

pub fn with_bundled_cli_extract_dir(self, dir: impl Into<PathBuf>) -> Self

Override the directory where the bundled CLI binary is extracted on first use. See Self::bundled_cli_extract_dir.

Only applies when the bundled-cli cargo feature is on. With bundled-cli disabled (default-features = false), set COPILOT_CLI_EXTRACT_DIR to relocate the build-time extraction (honored symmetrically at build and runtime), or use CliProgram::Path / COPILOT_CLI_PATH to point at a different binary at runtime.

pub fn with_mode(self, mode: ClientMode) -> Self

Set the SDK ClientMode. Use ClientMode::Empty for any scenario where CLI-like ambient behavior is unsafe (e.g. multi-user servers). Empty mode additionally requires Self::base_directory or Self::session_fs to be set, validated at Client::start.

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.