CLI v0.0.410+ auto-update breaks all SDK versions — --headless --stdio no longer accepted

[darthmolen]

Summary

The Copilot CLI auto-updated to v0.0.410+, which removed support for --headless --stdio. Since every version of @github/copilot-sdk (0.1.0 through 0.1.26-preview.0) internally spawns the CLI with these flags, all SDK versions are now broken when used with the current CLI.

Problem

The SDK calls:

copilot --headless --stdio --log-level error

CLI v0.0.410+ rejects these flags and exits with code 1. The replacement is --acp --stdio (Agent Client Protocol), which uses a different JSON-RPC method vocabulary (initialize instead of ping, session/new instead of session.create, etc.).

Impact

• Every SDK version is broken with CLI v0.0.410+
• The CLI auto-updates by default, so users discover the breakage at runtime
• There is no SDK configuration to change the CLI flags
• The CLI team made this change without coordinating with the SDK team

Current workaround

Users must pin the CLI binary to v0.0.403 and use --no-auto-update:

const client = new CopilotClient({
  cliPath: '/path/to/pinned/copilot-v0.0.403',
  // No way to prevent auto-update through SDK API
});

This is fragile — there's no official way to prevent auto-update through the SDK, and pinning to an old version means missing security fixes and model updates.

Request

1. Document the minimum and maximum CLI versions supported by each SDK release (related: Docs need to show a minimum CLI version required #137)
2. Either update the SDK to use --acp --stdio (the new protocol), or coordinate with the CLI team to restore --headless --stdio backward compatibility
3. Add a CLI version check to the SDK that fails fast with a clear error message instead of "Connection is closed"

Environment

• SDK: @github/copilot-sdk 0.1.23 (tested), all versions affected
• CLI: v0.0.410+ (broken), v0.0.403 (last working)
• Platform: Linux x64, but all platforms affected
• Related: We've filed a companion issue on copilot-cli (Breaking change: --headless --stdio removed without deprecation, breaks copilot-sdk and all downstream integrations copilot-cli#1606) about the breaking change.
• Related: Feature Request: Support ACP (Agent Client Protocol) Compatible CLIs #377 was closed as wontfix — but the reason we investigated ACP was because the CLI broke the SDK, not because we wanted to use a different CLI.

[github-actions]

Thank you for reporting this critical issue, @darthmolen!

Labels applied:

• bug — CLI backward compatibility breaking change
• priority/high — Affects all SDK versions and users
• sdk/dotnet, sdk/go, sdk/nodejs, sdk/python — Impacts all language SDKs

This is indeed a serious compatibility issue. The CLI v0.0.410+ removal of --headless --stdio breaks all current SDK releases. Your report is thorough and includes:

• ✅ Clear reproduction (all SDKs affected)
• ✅ Root cause analysis (CLI flag change)
• ✅ Workaround (pin to v0.0.403)
• ✅ Actionable requests (version documentation, protocol update, version checks)

Related to #137 (CLI version documentation) and #377 (ACP protocol support, closed as wontfix). The team will need to prioritize either updating all SDKs to use --acp --stdio or coordinating with CLI team on backward compatibility.

AI generated by Issue Triage Agent

[SteveSandersonMS]

@darthmolen Sorry for the inconvenience here with whatever you're facing.

Please note that some important parts of this issue report are incorrect:

• The underlying CLI has not moved to ACP as mandatory. The --stdio --headless flags are still supported and the core JSON-RPC protocol is unchanged.
• SDK consumers won't face unexpected breaking changes because the SDK (except on Go) uses its own bundled copy of Copilot CLI so isn't affected by whatever other version the user installs manually. You can still pass cliPath to override the instance it uses, but it never looks for any version from PATH.
• The SDK's bundled version does not auto-update.

To get past the versioning issue you're facing, could you please try updating to the latest SDK package? As long as your code doesn't pass any cliPath you'll be using the bundled compatible version.

[darthmolen]

@SteveSandersonMS Thanks for the quick response and for clarifying.

You're right on one point: the binary file at node_modules/@github/copilot-linux-x64/copilot is not replaced on disk. However, the CLI does delegate to newer versions at runtime via ~/.copilot/pkg/universal/. Here's what we observe:

# Fresh npm install of @github/copilot-sdk@0.1.22 (bundles @github/copilot@0.0.403)

$ md5sum node_modules/@github/copilot-linux-x64/copilot
db5ae0610e4b665b5faf7998ee545013

$ ./copilot --version --no-auto-update
GitHub Copilot CLI 0.0.403.

$ ./copilot --version                  # without --no-auto-update
GitHub Copilot CLI 0.0.410.

$ md5sum node_modules/@github/copilot-linux-x64/copilot
db5ae0610e4b665b5faf7998ee545013    # same hash — binary unchanged

The binary is a thin launcher. Without --no-auto-update, it downloads newer versions to ~/.copilot/pkg/universal/ and delegates execution. On our system, ~/.copilot/pkg/universal/ contains versions 0.0.395 through 0.0.410 — all downloaded automatically over time.

The fix you committed in PR #392 (Feb 6) is exactly right. Adding --no-auto-update to the SDK's CLI args prevents this runtime delegation. But that fix shipped in v0.1.23. Published SDK versions through v0.1.22 don't pass --no-auto-update, so any integrator on those versions experiences the version drift.

We've worked around this by passing --no-auto-update via cliArgs in our CopilotClient constructor.

Also worth noting: you mentioned the bundled CLI is "currently v0.0.414", but @github/copilot-sdk@0.1.25 (latest published) depends on ^0.0.411. Since ^0.0.x in npm semver pins exactly, that resolves to 0.0.411, not 0.0.414. Could the 0.0.414 you're seeing be the runtime-delegated version?

Separate finding for the CLI team: --headless --stdio is still accepted as a flag on all CLI versions we tested (0.0.403 through 0.0.414). It was never removed. Our original report conflated the auto-update version drift with flag removal. We'll update copilot-cli#1606 accordingly.

Requests:

1. Consider documenting the --no-auto-update workaround for integrators on older SDK versions
2. The needs-info label can be removed — this issue is explained by the pre-v0.1.23 SDK not passing --no-auto-update