claude-code - 💡(How to fix) Fix [DOCS] Plugin docs missing `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` for GitHub sources [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/env-vars

Section/Topic

Plugin-related environment variables, especially GitHub plugin and marketplace clone/auth behavior

Current Documentation

The environment variable index currently lists nearby plugin variables, but not this new one:

| CLAUDE_CODE_PLUGIN_CACHE_DIR | Override the plugins root directory. Despite the name, this sets the parent directory, not the cache itself: marketplaces and the plugin cache live in subdirectories under this path. Defaults to ~/.claude/plugins | | CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS | Timeout in milliseconds for git operations when installing or updating plugins (default: 120000). Increase this value for large repositories or slow network connections. See Git operations time out | | CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE | Set to 1 to keep the existing marketplace cache when a git pull fails instead of wiping and re-cloning. Useful in offline or airgapped environments where re-cloning would fail the same way. See Marketplace updates fail in offline environments | | CLAUDE_CODE_PLUGIN_SEED_DIR | Path to one or more read-only plugin seed directories, separated by : on Unix or ; on Windows. Use this to bundle a pre-populated plugins directory into a container image. Claude Code registers marketplaces from these directories at startup and uses pre-cached plugins without re-cloning. See Pre-populate plugins for containers |

Related plugin docs also describe GitHub and SSH/HTTPS source handling without mentioning this setting:

Add a GitHub repository that contains a .claude-plugin/marketplace.json file using the owner/repo format—where owner is the GitHub username or organization and repo is the repository name.

The url field also accepts a GitHub shorthand (owner/repo) or SSH URLs ([email protected]:owner/repo.git).

Claude Code supports installing plugins from private repositories. For manual installation and updates, Claude Code uses your existing git credential helpers, so HTTPS access via gh auth login, macOS Keychain, or git-credential-store works the same as in your terminal. SSH access works as long as the host is already in your known_hosts file and the key is loaded in ssh-agent, since Claude Code suppresses interactive SSH prompts for the host fingerprint and key passphrase.

What's Wrong or Missing?

The v2.1.141 changelog adds CLAUDE_CODE_PLUGIN_PREFER_HTTPS to clone GitHub plugin sources over HTTPS instead of SSH for environments without a GitHub SSH key, but that setting is not documented in the environment variable reference or in the plugin marketplace/discovery guidance.

That leaves a gap for users who:

1. add marketplaces or plugin sources using GitHub shorthand such as owner/repo, and
2. authenticate to GitHub with HTTPS credentials or tokens rather than an SSH key.

The current docs explain GitHub shorthand, SSH URLs, and private-repository auth expectations, but they do not tell readers that there is now a dedicated setting to prefer HTTPS for GitHub plugin source clones.

Suggested Improvement

Add a CLAUDE_CODE_PLUGIN_PREFER_HTTPS entry to https://code.claude.com/docs/en/env-vars that documents:

• what the variable changes (GitHub plugin source clones use HTTPS instead of SSH)
• which source forms it affects (for example, GitHub shorthand / GitHub-backed plugin sources)
• when to use it (environments without a GitHub SSH key, but with HTTPS credentials, gh auth, or tokens)
• any accepted values and a minimal shell example

Then add a short note or cross-reference in the GitHub/plugin marketplace docs so readers who are following GitHub source setup instructions can discover the setting without hunting through release notes.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

This appears to be a new documentation gap introduced with changelog entry v2.1.141.