API To Query Common Things: Copilot CLI Status, Auth, Models

[jamesmontemagno]

Problem

Today, querying common Copilot CLI information such as service status, authentication state, and available models requires manual calls or indirect workarounds. For example, developers might have to:

• Execute shell commands to check Copilot CLI status or authentication.
• Parse CLI outputs manually to determine if the user is logged in or which models are supported.
• Implement custom scripts or wrappers to extract this real-time information, resulting in duplicated logic and fragile integrations.

This approach creates friction for SDK consumers and increases the likelihood of errors or inconsistent experiences across projects.

Document “how we do it today”

Copilot CLI status

Typical approach today:

• Run a CLI command (e.g., copilot --version and/or a copilot status-style command if available).
• Interpret exit codes and parse text output.

Pain points:

• Output can change between versions (breaking parsers).
• Error cases aren’t strongly typed.
• Consumers often re-implement the same detection logic.

Authentication status

Typical approach today:

• Run a CLI command to check auth/login state (or attempt an API call and infer auth from failure).
• Parse output to determine whether the user is logged in.
• If needed, run a login flow and then retry.

Pain points:

• Hard to reliably distinguish “not logged in” vs “expired” vs “needs reauth”.
• Unclear which account/tenant is active (when multiple identities are possible).
• Token expiry and scopes/capabilities are not readily accessible.

Available models

Typical approach today:

• Hardcode assumptions by CLI version.
• Scrape docs or attempt requests and fall back.
• Parse outputs from a “models list” command if present.

Pain points:

• Hard to confidently know what’s available for this user and this environment.
• No structured metadata (capabilities/limits/availability).

Proposal: New SDK APIs

The Copilot SDK should provide dedicated, strongly-typed APIs to programmatically query:

1. Copilot CLI Status

   • Is the Copilot CLI installed?
   • Is it usable / healthy?
   • What version is installed?

2. Authentication State

   • Is the user authenticated?
   • Which account is active?
   • When does authentication expire (if applicable)?
   • Is re-auth required?

3. Available Models

   • List models available for the current CLI version/account.
   • Include model metadata (name/id, capabilities, availability, restrictions/limits).

Suggested API design (C# examples)

public interface ICopilotEnvironmentClient
{
    Task<CopilotCliStatus> GetCopilotCliStatusAsync(CancellationToken cancellationToken = default);
    Task<CopilotAuthStatus> GetCopilotAuthStatusAsync(CancellationToken cancellationToken = default);
    Task<IReadOnlyList<CopilotModelInfo>> GetCopilotSupportedModelsAsync(CancellationToken cancellationToken = default);
}

public sealed record CopilotCliStatus(
    bool IsInstalled,
    bool IsHealthy,
    string? Version,
    string? InstallPath,
    string? StatusMessage);

public sealed record CopilotAuthStatus(
    bool IsAuthenticated,
    string? Account,
    DateTimeOffset? ExpiresAt,
    bool RequiresReauth,
    string? StatusMessage);

public sealed record CopilotModelInfo(
    string Id,
    string DisplayName,
    IReadOnlyList<string> Capabilities,
    bool IsDefault,
    string? Notes);

Behavior / Error handling expectations

• Strongly-typed results for common states (not installed, not authenticated, expired auth, CLI unavailable).
• Avoid requiring consumers to parse raw strings.
• Where raw output is useful, include it as an optional diagnostic field (or attach via exceptions).

Benefits

• Simplifies integrations: no manual shelling out and parsing.
• Consistent behavior across projects and platforms.
• Reduces duplicated logic and enables better UX in downstream tools.

Acceptance criteria

• SDK exposes APIs to query CLI status, auth status, and available models.
• APIs return structured data (strong typing) and predictable error states.
• Documentation includes “how to do it today” vs “recommended SDK approach”.
• Samples/tests demonstrate expected behavior across common scenarios (not installed, not logged in, expired auth, etc.).

[github-actions]

Thank you @jamesmontemagno for this detailed feature request!

I've labeled this as an enhancement. This proposal for adding structured APIs to query Copilot CLI status, authentication state, and available models is well-documented with clear problem statements, current pain points, and proposed solutions with acceptance criteria.

The suggested API design looks solid, particularly the focus on:

• Strong typing vs parsing raw CLI output
• Comprehensive authentication state details
• Model metadata and capabilities

Since this would impact all SDK implementations, this will likely benefit from input across the .NET, Go, Node.js, and Python teams.

AI generated by Issue Triage Agent