CLI Troubleshooting

Troubleshooting guide for the MyClaude CLI covering installation, authentication, publishing, product installation, and network issues.

Each entry follows the pattern: symptom, cause, solution. If you do not find your issue here, open an issue on GitHub.

Installation issues

"command not found: myclaude" after install

Cause: The npm global bin directory is not in your shell's PATH.

Solution: Find the directory and add it to your PATH:

$ npm bin -g
# /home/user/.npm-global/bin

$ echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc
$ source ~/.zshrc
$ myclaude --version

On Windows, the global bin is typically %APPDATA%\npm. Add it via System Properties, Environment Variables, then restart your terminal.

"permission denied" during global install on Linux or macOS

Cause: npm is trying to write to a system-owned directory (e.g., /usr/local/lib).

Solution: Configure npm to use a user-owned prefix instead of using sudo:

$ mkdir -p ~/.npm-global
$ npm config set prefix ~/.npm-global
$ echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc
$ npm install -g @myclaude-cli/cli

Do not run npm install -g with sudo. It causes file ownership problems that affect all global packages.

"unsupported engine" or "node: not found"

Cause: Node.js is not installed or the installed version is below the minimum requirement (18.0.0).

Solution: Install a current LTS release:

$ nvm install --lts
$ nvm use --lts
$ node --version
# v22.x.x

If you do not have nvm, download Node.js directly from nodejs.org. The CLI requires Node.js 18+ because it depends on the native fetch API and node:crypto module.

"myclaude" resolves to a different program

Cause: Another program named myclaude is in your PATH ahead of the npm global bin.

Solution: Check which binary is resolving:

$ which myclaude
# /usr/local/bin/myclaude   <-- not the MyClaude CLI you expected

$ npm bin -g
# /home/user/.npm-global/bin

Either reorder your PATH to place the npm global bin first, or invoke the MyClaude CLI explicitly:

$ npx @myclaude-cli/cli --version

Alternatively, create an alias in your shell profile:

$ echo 'alias mcli="$(npm bin -g)/myclaude"' >> ~/.zshrc
$ source ~/.zshrc

Windows: "execution policy" error in PowerShell

Cause: PowerShell's execution policy blocks the npm shim script.

Solution: Allow locally installed scripts to run:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Then restart PowerShell and retry myclaude --version.

Authentication issues

"Error: not authenticated. Run myclaude login."

Cause: No stored credentials found. You have not logged in yet, or a previous myclaude logout cleared your session.

Solution:

$ myclaude login

"Error: session expired."

Cause: Your refresh token has exceeded its lifetime. Refresh tokens expire after 90 days of issue or after 10 days of inactivity (whichever comes first).

Solution:

$ myclaude login

This creates a new session. No data is lost -- your installed products, purchase history, and published products are unaffected.

"Error: invalid credentials."

Cause: Incorrect email or password.

Solution: Double-check your email address and password. If you have forgotten your password, reset it at myclaude.sh/forgot-password. The CLI does not support password reset flows.

"Error: keychain access denied."

Cause: The CLI cannot read from or write to the OS keychain. On macOS, this can happen when keychain access is denied by a system prompt. On Linux, the Secret Service API may not be running.

Solution:

• macOS: Open Keychain Access, search for vault-marketplace, and verify the CLI has access. If prompted by the system, click "Always Allow".
• Linux: Ensure gnome-keyring-daemon or kwallet is running. In a headless environment, use MYCLAUDE_TOKEN instead.
• Windows: Verify Credential Manager is accessible. Run cmdkey /list to check.

If you cannot resolve keychain access, use the environment variable override:

$ export MYCLAUDE_TOKEN="your-token-here"

"Warning: keychain unavailable, using file fallback."

Cause: No OS keychain detected. Common on headless servers, Docker containers, and some WSL configurations.

Solution: This is not an error -- the CLI falls back to storing the refresh token at ~/.myclaude/credentials with chmod 600. For CI/CD environments, prefer MYCLAUDE_TOKEN over the file fallback. See CLI Authentication for details.

myclaude whoami shows the wrong account

Cause: You logged in with a different account than intended.

Solution:

$ myclaude logout
$ myclaude login
# Email: correct-account@example.com

Publishing issues

"Error: version must be higher than currently published."

Cause: The version field in your vault.yaml is equal to or lower than the version currently live on the marketplace.

Solution: Increment the version in vault.yaml before publishing:

# vault.yaml
version: "1.1.0"  # was 1.0.0

The CLI enforces monotonically increasing SemVer versions. You cannot re-publish the same version number.

"Error: content policy violation."

Cause: The pre-publish content scanner detected a policy violation in your product files.

Solution: Run myclaude scan to see the specific violations:

$ myclaude scan
# Scanning ./ ...
# ERROR: SKILL.md line 42 — detected pattern: Stripe Secret Key
# Scan failed. 1 error found.

Fix the flagged content, or if the detection is a false positive, add the file to .vaultignore:

# .vaultignore
test-fixtures/mock-keys.txt

"Error: secret detected in product files."

Cause: The secret scanner found what appears to be an API key, private key, or credential in your product files. This is a hard blocker -- the CLI will not publish until the issue is resolved.

Solution: Remove the secret from your product files. If the flagged content is a false positive (for example, a regex pattern in documentation that resembles a key), add the file to .vaultignore. The scanner checks for:

• AWS access keys and secret keys
• Firebase API keys
• Stripe secret keys and webhook secrets
• Private key headers (RSA, EC)
• Generic token patterns (api_key = "...")
• .env files

"Error: vault.yaml not found."

Cause: You are running myclaude publish from a directory that does not contain a vault.yaml file.

Solution: Either cd into the product directory, or run myclaude init to scaffold a new product:

$ myclaude init my-product --category skill
$ cd my-product
$ myclaude publish

"Error: required field missing: description"

Cause: A required field in vault.yaml is empty or absent.

Solution: Run myclaude scan to see all missing fields, then fill them in:

$ myclaude scan
# ERROR: vault.yaml — required field missing: description
# ERROR: vault.yaml — required field missing: author

"Error: author does not match authenticated user."

Cause: The author field in vault.yaml does not match the username of the currently authenticated account.

Solution: Update the author field to match your MyClaude username:

# vault.yaml
author: "your-username"  # must match myclaude whoami output

Or log in as the correct account:

$ myclaude whoami
# Logged in as @other-account

$ myclaude logout && myclaude login
# Email: correct@example.com

Product installation issues

"Error: product not found."

Cause: The product handle is misspelled, the product has been removed, or it has not passed admin review yet.

Solution: Search for the product to verify its handle:

$ myclaude search "product name"

Products published via CLI start in pending_review status. They are not installable until approved by a MyClaude admin.

"Error: purchase required."

Cause: You are trying to install a paid product that you have not purchased.

Solution: Run the install command and complete the purchase flow:

$ myclaude install @creator/product
# @creator/product requires purchase ($4.00)
# Opening checkout... [browser opens]

The CLI opens Stripe Checkout in your browser. After payment, installation resumes automatically.

Installed product files not visible to Claude Code

Cause: The product was installed to a directory that Claude Code does not scan, or Claude Code needs to be restarted to pick up new files.

Solution: Verify the install path:

$ myclaude list
# @creator/product    1.0.0   skill   .claude/skills/product/

Ensure the install path is under .claude/ in your project root. If it is, restart your Claude Code session -- it discovers installed skills on startup.

"Error: checksum mismatch."

Cause: The downloaded file does not match the SHA-256 checksum published with the product. This could indicate a corrupted download or a tampered package.

Solution: Retry the install:

$ myclaude install @creator/product --force

If the checksum mismatch persists, report it on GitHub. Do not use the product until the issue is resolved.

Product installed but outdated version

Cause: A specific version was pinned in a previous install, or the lockfile references an older version.

Solution: Update the specific product to its latest version:

$ myclaude update @creator/product
# @creator/product: 1.0.0 -> 1.2.0
# Updated.

Or check what version is installed first:

$ myclaude list
# @creator/product    1.0.0   skill   .claude/skills/product/

$ myclaude info @creator/product
# Version: 1.2.0 (latest)

"Error: path traversal detected in archive."

Cause: The product archive contains file paths that attempt to escape the install directory (e.g., paths containing ..). This is a security check that prevents malicious packages from writing files outside the expected location.

Solution: This is a safety mechanism. Do not install the product. Report it on GitHub with the product handle.

"Error: archive exceeds maximum file count."

Cause: The product archive contains more than 1000 files. This limit exists to prevent zip bombs and excessively large packages.

Solution: This is a product-side issue. If you are the creator, reduce the file count by consolidating files or excluding unnecessary content via .vaultignore. If you are a buyer, contact the product creator.

Network issues

"Error: network timeout."

Cause: The CLI could not reach the MyClaude API or Firebase Auth servers within the default timeout period.

Solution: Check your internet connection, then retry. If you are behind a corporate proxy, configure it:

$ export HTTPS_PROXY=http://proxy.company.com:8080
$ myclaude search "test"

The CLI respects the standard HTTPS_PROXY and HTTP_PROXY environment variables.

"Error: cannot reach VAULT servers."

Cause: DNS resolution failed or the MyClaude API is unreachable.

Solution: Verify connectivity to the API endpoint:

$ curl -I https://myclaude.sh/api/health

If this fails, the issue is network-level (firewall, DNS, or outage). Check status.myclaude.sh for service status.

Slow downloads behind a VPN

Cause: VPN routing can add latency to connections to Firebase Storage and Cloudflare R2.

Solution: If possible, allowlist the following domains in your VPN split-tunnel configuration:

• myclaude.sh
• firebasestorage.googleapis.com
• identitytoolkit.googleapis.com
• securetoken.googleapis.com

SSL certificate errors behind corporate proxy

Cause: Corporate proxies that perform TLS inspection replace upstream SSL certificates with their own. Node.js does not trust these certificates by default.

Solution: Point Node.js to your corporate CA bundle:

$ export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
$ myclaude search "test"

Add this export to your shell profile for persistence. Do not set NODE_TLS_REJECT_UNAUTHORIZED=0 -- this disables all certificate verification and is a security risk.

Platform-specific issues

macOS: "myclaude" blocked by Gatekeeper

Cause: On rare occasions, macOS Gatekeeper may quarantine globally installed npm binaries.

Solution: Remove the quarantine attribute:

$ xattr -d com.apple.quarantine "$(which myclaude)"

Linux: "Error: DBUS_SESSION_BUS_ADDRESS not set"

Cause: The Secret Service API (used for keychain storage) requires a D-Bus session, which is not available in some terminal environments, particularly over SSH or in containers.

Solution: Either start a D-Bus session manually or use MYCLAUDE_TOKEN for authentication:

$ export MYCLAUDE_TOKEN="your-token-here"
$ myclaude whoami

WSL: keychain not accessible from WSL2

Cause: WSL2 does not have direct access to Windows Credential Manager, and may not have a Linux keychain daemon running.

Solution: The CLI falls back to file-based storage automatically. For explicit control, use MYCLAUDE_TOKEN:

$ export MYCLAUDE_TOKEN="your-token-here"

Alternatively, install and start gnome-keyring in your WSL2 environment:

$ sudo apt install gnome-keyring
$ eval $(gnome-keyring-daemon --start)
$ myclaude login

Diagnostic commands

When reporting an issue, include the output of these commands:

For a comprehensive diagnostic, run them together:

$ myclaude --version && node --version && npm --version && myclaude whoami && myclaude config list

Getting help

• GitHub Issues: github.com/anthropics/myclaude-cli/issues -- bug reports and feature requests
• MyClaude Community: myclaude.sh/community -- discussions and Q&A
• CLI help flag: Every command supports --help for inline usage documentation:

$ myclaude publish --help
$ myclaude install --help

Related pages

• CLI Installation -- requirements and first-time setup
• CLI Authentication -- token lifecycle and CI/CD auth
• CLI Configuration -- config file and environment variables
• CLI Commands Reference -- complete reference for all 12 commands