Incorrect keyboard shortcut documentation for newline on macOS

[mohammedmanna-skyscanner]

Description

The help/settings documentation incorrectly states that Shift + Enter creates a newline in the command prompt on macOS.

Current Behavior

• Documentation shows: Shift + Enter for newline
• Actual behavior: Shift + Enter submits the command (same as just pressing Enter)

Expected Behavior

• The correct keyboard shortcut for creating a newline on macOS is Option + Enter

Platform

• OS: macOS (Darwin 25.2.0)
• Claude Code CLI

Steps to Reproduce

1. Open Claude Code CLI on macOS
2. Check help (?) settings for newline keyboard shortcut
3. Try using Shift + Enter - it submits the command instead of creating a newline
4. Use Option + Enter - this correctly creates a newline

Suggested Fix

Update the documentation/help settings to show the correct keyboard shortcut for macOS:

• macOS: Option + Enter
• Not: Shift + Enter

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Shift + Enter submits prompt instead of inserting newline (contradicts documented shortcuts) #7958
2. [BUG] Shift+Enter keybinding doesn't add a new line, but starts the prompt #11539
3. [Bug] VSCode Extension: Keyboard Shortcuts Broken on MacOS #8177

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[coygeek]

What’s FIXED

The documentation has been updated to correctly identify the primary newline shortcut for macOS users and provides terminal-specific configuration steps to resolve the submission behavior reported.

• Corrected Shortcut Table: On the Interactive mode page (https://code.claude.com/docs/en/interactive-mode#multiline-input), a new entry has been added to the "Multiline input" table specifically for macOS. It now explicitly states that Option+Enter is the "Default on macOS."
• Terminal-Specific Nuance: The documentation now distinguishes between standard macOS behavior and specific terminal emulators. The same table clarifies that Shift+Enter only works "out of the box" in specific terminals like iTerm2, WezTerm, Ghostty, and Kitty, rather than being a universal macOS instruction.
• Configuration Guide: The Optimize your terminal setup page (https://code.claude.com/docs/en/terminal-config#line-breaks) now contains a dedicated section for "Set up Option+Enter." It provides explicit steps for macOS Terminal.app (checking "Use Option as Meta Key") and iTerm2/VS Code (setting the Option key to "Esc+").
• Automated Setup Command: Reference to the /terminal-setup command has been added to the Terminal configuration page (https://code.claude.com/docs/en/terminal-config#set-up-shift-enter-for-other-terminals), which automates the binding for users in VS Code, Alacritty, Zed, and Warp where Shift+Enter would otherwise submit the command.

What’s UNRESOLVED

While the core issue is addressed, there is one minor inconsistency remaining in the documentation:

• VS Code Extension Specifics: On the Use Claude Code in VS Code page (https://code.claude.com/docs/en/vs-code#use-the-prompt-box), the text still states "Press Shift+Enter to add a new line without sending" without mentioning the macOS Option+Enter alternative. While this may be accurate for the graphical extension UI, users switching between the Extension and the CLI (as suggested on the same page) may find the conflicting instructions for the same IDE environment confusing.

Conclusion

The documentation now accurately reflects that Option+Enter is the standard newline shortcut for macOS and provides the necessary configuration steps for various terminal environments to prevent accidental command submission. The primary inaccuracies in the CLI documentation have been fully addressed.

This issue as resolved.

[oderwat]

Neither shift nor option works anymore in Claude Desktop > Code since some days. Where should that get reported?

[g-i-o-r-g-i-o]

This is marked as a duplicate of a windows problem #21360
is this correct?

Shouldn't windows have a separate bug?

[g-i-o-r-g-i-o]

Each and every declination of Claude (app, vscode, terminal, web) has its shortcuts, and this is crazy

At least make the enter, shift enter, ctrl enter (newline and/or send), work the same way in all the apps?

[github-actions]

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