[DOCS] Windows Native Install: Missing terminal restart instructions and potential path resolution issues

[coygeek]

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/setup

Section/Topic

Native Install (Recommended) -> Windows PowerShell / Windows CMD tabs.

Current Documentation

The documentation provides the following commands for Windows installation:

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

What's Wrong or Missing?

There are two primary issues with this section for Windows users:

1. Missing Terminal Restart Step: The installer adds ~/.local/bin to the user's PATH, but Windows environment variable changes do not propagate to active terminal sessions. Users who immediately try to run claude following these commands will receive a "command not found" error, leading to a frustrating first-user experience.
2. Path Resolution Risks (CMD): In the CMD string, install.cmd is executed without quotes. If a user runs this from a directory containing spaces in the path, the chain might fail depending on how the shell handles the temporary file.
3. Lack of Visibility for Troubleshooting: While the "Troubleshooting" page contains instructions on how to manually add the path, the main "Setup" page does not warn the user that a restart is required or link directly to the troubleshooting section for path errors.

Suggested Improvement

I suggest adding a specific "Step 1.5" or a prominent Note immediately following the installation command boxes.

Proposed Text Addition:

⚠️ Note for Windows Users:
After the installation script finishes, you must close and reopen your terminal (PowerShell or CMD) for the claude command to be recognized. This allows Windows to refresh your PATH environment variable to include the new installation directory.

If you still receive a "command not found" error after restarting, verify that %USERPROFILE%\.local\bin has been added to your User Path environment variables.

Impact

High - Prevents users from using a feature

Additional Context

• The troubleshooting guide at docs/en/troubleshooting.md under "Windows: 'installMethod is native, but claude command not found'" already identifies this exact solution (Step 3: Restart your terminal). Surfacing this earlier in the setup.md file will reduce support burden and "broken" installation reports.
• Many developers using CMD on Windows might be working in folders like C:\Users\Name\Google Drive\... where spaces are common; ensuring the documentation encourages a robust execution environment is beneficial.

[coygeek]

This review compares the reported issues regarding the Windows installation workflow with the current state of the documentation at https://code.claude.com/docs/en/setup and associated pages.

What’s FIXED

• Troubleshooting Detail: The specific instructions for resolving a missing path on Windows have been maintained and are accurately detailed at https://code.claude.com/docs/en/troubleshooting#windows-installmethod-is-native-but-claude-command-not-found. This section correctly identifies "Step 3: Restart your terminal" as a necessary action.
• Health Checks: A tip has been added to the main setup page at https://code.claude.com/docs/en/setup encouraging users to run claude doctor to check installation health, which helps diagnose path issues after the fact.

What’s UNRESOLVED

• Missing Proactive Restart Instruction: The primary request to add a "Step 1.5" or a prominent note immediately following the installation commands on https://code.claude.com/docs/en/setup has been ignored. The current text still moves directly from installation to "start Claude Code: claude." Because Windows does not broadcast PATH changes to existing shells, a user following these instructions verbatim will still encounter a "command not found" error immediately after installation.
• Unsafe CMD Syntax: The installation string for Windows CMD at https://code.claude.com/docs/en/setup (and replicated at https://code.claude.com/docs/en/overview) remains:
  curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
  This still lacks quotes around the execution of install.cmd. As noted in the original issue, if a user is working within a directory path containing spaces, the command chain may fail or exhibit unpredictable behavior.
• Low Visibility for Path Troubleshooting: While the troubleshooting page is linked generally, the specific suggestion to provide a direct link to the "User Path environment variables" instructions within the setup flow was not implemented. Users are forced to hunt through the general troubleshooting guide when the "command not found" error inevitably occurs.

Conclusion

I am keeping this issue open.

While the technical information required to fix a broken path exists deep within the documentation, the "Native Install" instructions on the primary setup page (https://code.claude.com/docs/en/setup) remain technically incomplete for Windows users. The documentation currently sets users up for an immediate failure by not mentioning the required terminal restart and by using a potentially fragile CMD execution string.

To resolve this, the "Native Install" tab for Windows should be updated to include a warning about terminal restarts, and the CMD string should be quoted for robustness.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.