Package com.github.copilot.sdk.json

Class CopilotClientOptions

java.lang.Object
com.github.copilot.sdk.json.CopilotClientOptions
public class CopilotClientOptions extends Object
Configuration options for creating a CopilotClient.

This class provides a fluent API for configuring how the client connects to and manages the Copilot CLI server. All setter methods return this for method chaining.

Example Usage


 var options = new CopilotClientOptions().setCliPath("/usr/local/bin/copilot").setLogLevel("debug")
 		.setAutoStart(true);

 var client = new CopilotClient(options);
Since:
1.0.0
See Also:

  • Constructor Details

    • CopilotClientOptions

      public CopilotClientOptions()

  • Method Details

    • isAutoRestart

      @Deprecated public boolean isAutoRestart()
      Deprecated.
      This option has no effect and will be removed in a future release.
      Returns whether the client should automatically restart the server on crash.
      Returns:
      the auto-restart flag value (no longer has any effect)

    • setAutoRestart

      @Deprecated public CopilotClientOptions setAutoRestart(boolean autoRestart)
      Deprecated.
      This option has no effect and will be removed in a future release.
      Sets whether the client should automatically restart the CLI server if it crashes unexpectedly.
      Parameters:
      autoRestart - ignored — this option no longer has any effect
      Returns:
      this options instance for method chaining

    • isAutoStart

      public boolean isAutoStart()
      Returns whether the client should automatically start the server.
      Returns:
      true to auto-start (default), false for manual start

    • setAutoStart

      public CopilotClientOptions setAutoStart(boolean autoStart)
      Sets whether the client should automatically start the CLI server when the first request is made.
      Parameters:
      autoStart - true to auto-start, false for manual start
      Returns:
      this options instance for method chaining

    • getCliArgs

      public String[] getCliArgs()
      Gets the extra CLI arguments.

      Returns a shallow copy of the internal array, or null if no arguments have been set.

      Returns:
      a copy of the extra arguments, or null

    • setCliArgs

      public CopilotClientOptions setCliArgs(String[] cliArgs)
      Sets extra arguments to pass to the CLI process.

      These arguments are prepended before SDK-managed flags. A shallow copy of the provided array is stored. If null or empty, the existing arguments are cleared.

      Parameters:
      cliArgs - the extra arguments to pass, or null/empty to clear
      Returns:
      this options instance for method chaining

    • getCliPath

      public String getCliPath()
      Gets the path to the Copilot CLI executable.
      Returns:
      the CLI path, or null to use "copilot" from PATH

    • setCliPath

      public CopilotClientOptions setCliPath(String cliPath)
      Sets the path to the Copilot CLI executable.
      Parameters:
      cliPath - the path to the CLI executable
      Returns:
      this options instance for method chaining

    • getCliUrl

      public String getCliUrl()
      Gets the URL of an existing CLI server to connect to.
      Returns:
      the CLI server URL, or null to spawn a new process

    • setCliUrl

      public CopilotClientOptions setCliUrl(String cliUrl)
      Sets the URL of an existing CLI server to connect to.

      When provided, the client will not spawn a CLI process but will connect to the specified URL instead. Format: "host:port" or "http://host:port".

      Note: This is mutually exclusive with setUseStdio(boolean) and setCliPath(String).

      Parameters:
      cliUrl - the CLI server URL to connect to (must not be null or empty)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if cliUrl is null or empty

    • getCwd

      public String getCwd()
      Gets the working directory for the CLI process.
      Returns:
      the working directory path

    • setCwd

      public CopilotClientOptions setCwd(String cwd)
      Sets the working directory for the CLI process.
      Parameters:
      cwd - the working directory path (must not be null or empty)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if cwd is null or empty

    • getEnvironment

      public Map<String,String> getEnvironment()
      Gets the environment variables for the CLI process.

      Returns a shallow copy of the internal map, or null if no environment has been set.

      Returns:
      a copy of the environment variables map, or null

    • setEnvironment

      public CopilotClientOptions setEnvironment(Map<String,String> environment)
      Sets environment variables to pass to the CLI process.

      When set, these environment variables replace the inherited environment. A shallow copy of the provided map is stored. If null or empty, the existing environment is cleared.

      Parameters:
      environment - the environment variables map, or null/empty to clear
      Returns:
      this options instance for method chaining

    • getExecutor

      public Executor getExecutor()
      Gets the executor used for internal asynchronous operations.
      Returns:
      the executor, or null to use the default ForkJoinPool.commonPool()

    • setExecutor

      public CopilotClientOptions setExecutor(Executor executor)
      Sets the executor used for internal asynchronous operations.

      When provided, the SDK uses this executor for all internal CompletableFuture combinators instead of the default ForkJoinPool.commonPool(). This allows callers to isolate SDK work onto a dedicated thread pool or integrate with container-managed threading.

      Passing null reverts to the default ForkJoinPool.commonPool() behavior.

      Parameters:
      executor - the executor to use, or null for the default
      Returns:
      this options instance for fluent chaining

    • getGitHubToken

      public String getGitHubToken()
      Gets the GitHub token for authentication.
      Returns:
      the GitHub token, or null to use other authentication methods

    • setGitHubToken

      public CopilotClientOptions setGitHubToken(String gitHubToken)
      Sets the GitHub token to use for authentication.

      When provided, the token is passed to the CLI server via environment variable. This takes priority over other authentication methods.

      Parameters:
      gitHubToken - the GitHub token (must not be null or empty)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if gitHubToken is null or empty

    • getGithubToken

      @Deprecated public String getGithubToken()
      Deprecated.
      Use getGitHubToken() instead.
      Gets the GitHub token for authentication.
      Returns:
      the GitHub token, or null to use other authentication methods

    • setGithubToken

      @Deprecated public CopilotClientOptions setGithubToken(String githubToken)
      Deprecated.
      Use setGitHubToken(String) instead.
      Sets the GitHub token to use for authentication.
      Parameters:
      githubToken - the GitHub token
      Returns:
      this options instance for method chaining

    • getLogLevel

      public String getLogLevel()
      Gets the log level for the CLI process.
      Returns:
      the log level (default: "info")

    • setLogLevel

      public CopilotClientOptions setLogLevel(String logLevel)
      Sets the log level for the CLI process.

      Valid levels include: "error", "warn", "info", "debug", "trace".

      Parameters:
      logLevel - the log level (must not be null or empty)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if logLevel is null or empty

    • getOnListModels

      public Supplier<CompletableFuture<List<ModelInfo>>> getOnListModels()
      Gets the custom handler for listing available models.
      Returns:
      the handler, or null if not set

    • setOnListModels

      public CopilotClientOptions setOnListModels(Supplier<CompletableFuture<List<ModelInfo>>> onListModels)
      Sets a custom handler for listing available models.

      When provided, listModels() calls this handler instead of querying the CLI server. Useful in BYOK (Bring Your Own Key) mode to return models available from your custom provider.

      Parameters:
      onListModels - the handler that returns the list of available models (must not be null)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if onListModels is null

    • getPort

      public int getPort()
      Gets the TCP port for the CLI server.
      Returns:
      the port number, or 0 for a random port

    • setPort

      public CopilotClientOptions setPort(int port)
      Sets the TCP port for the CLI server to listen on.

      This is only used when isUseStdio() is false.

      Parameters:
      port - the port number, or 0 for a random port
      Returns:
      this options instance for method chaining

    • getTelemetry

      public TelemetryConfig getTelemetry()
      Gets the OpenTelemetry configuration for the CLI server.
      Returns:
      the telemetry config, or null
      Since:
      1.2.0

    • setTelemetry

      public CopilotClientOptions setTelemetry(TelemetryConfig telemetry)
      Sets the OpenTelemetry configuration for the CLI server.

      When set, the CLI server is started with OpenTelemetry instrumentation enabled using the provided settings.

      Parameters:
      telemetry - the telemetry configuration
      Returns:
      this options instance for method chaining
      Since:
      1.2.0

    • getUseLoggedInUser

      public Boolean getUseLoggedInUser()
      Returns whether to use the logged-in user for authentication.
      Returns:
      true to use logged-in user auth, false to use only explicit tokens, or null to use default behavior

    • setUseLoggedInUser

      public CopilotClientOptions setUseLoggedInUser(Boolean useLoggedInUser)
      Sets whether to use the logged-in user for authentication.

      When true, the CLI server will attempt to use stored OAuth tokens or gh CLI auth. When false, only explicit tokens (gitHubToken or environment variables) are used. Default: true (but defaults to false when gitHubToken is provided).

      Passing null is equivalent to passing Boolean.FALSE.

      Parameters:
      useLoggedInUser - true to use logged-in user auth, false or null otherwise
      Returns:
      this options instance for method chaining

    • isUseStdio

      public boolean isUseStdio()
      Returns whether to use stdio transport instead of TCP.
      Returns:
      true to use stdio (default), false to use TCP

    • setUseStdio

      public CopilotClientOptions setUseStdio(boolean useStdio)
      Sets whether to use stdio transport instead of TCP.

      Stdio transport is more efficient and is the default. TCP transport can be useful for debugging or connecting to remote servers.

      Parameters:
      useStdio - true to use stdio, false to use TCP
      Returns:
      this options instance for method chaining

    • clone

      public CopilotClientOptions clone()
      Creates a shallow clone of this CopilotClientOptions instance.

      Array properties (like cliArgs) are copied into new arrays so that modifications to the clone do not affect the original. The environment map is also copied to a new map instance. Other reference-type properties are shared between the original and clone.

      Returns:
      a clone of this options instance