aws / aws/amazon-q-developer-cli

Q CLI doctor fails with PATH and shell integration issues

Open
#2,981 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2k
Forks
439
PR merge metrics
No merged PRs in 30d

Description

### Checks

- [x] I have searched [github.com/aws/amazon-q-developer-cli/issues](https://github.com/aws/amazon-q-developer-cli/issues?q=) and there are no duplicates of my issue
- [x] I have run `q doctor` in the affected terminal session
- [x] I have run `q restart` and replicated the issue again

### Operating system

macOS 15.7.0 (24G222)

### Expected behaviour

Q CLI doctor should pass all checks when ~/.local/bin is added to PATH and shell integration is properly configured

### Actual behaviour

Q CLI doctor continues to report "PATH contains ~/.local/bin: Path does not contain ~/.local/bin" even after adding export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc and ensuring Q CLI post integration is sourced last

```
[chat-transcript]
The `payments-genai-mcp-server` package doesn't appear to be publicly available. This could be:

1. **An internal Amazon package** - If this is an internal tool, you may need to:
- Install it from an internal package repository
- Clone it from an internal Git repository
- Use Amazon-specific installation tools

2. **A private or unreleased package** - You might need:
- Access credentials

> q doctor

[Tool uses: execute_bash]

> Y

The Q CLI doctor found an issue with your PATH configuration. The `~/.local/bin` directory is not in your PATH, which is needed for some Q CLI functionality.

To fix this, add `~/.local/bin` to your PATH by adding this line to your shell configuration file:
[Tool uses: execute_bash]

Since you're using zsh, add this to your `~/.zshrc` file:
[Tool uses: fs_write]

> Y

Now reload your shell configuration:
[Tool uses: execute_bash]

> Y

There's a syntax error in the Q CLI shell configuration. Let's run the doctor again to see if the PATH issue is resolved:
[Tool uses: execute_bash]

> y

The PATH still isn't updated. Let me check the current PATH and manually export it for this session:
[Tool uses: execute_bash]

> y

[Tool uses: execute_bash]

> y

The doctor is still reporting the PATH issue. Let me check what Q CLI expects for the shell integration:
[Tool uses: fs_read]

The Q CLI integration expects the post integration to be sourced last. Let me fix the shell configuration by moving the PATH export before the Q post block:
[Tool uses: fs_write]

> y

Now run the doctor again:
[Tool uses: execute_bash]

> y

The issue persists. Let me restart the shell to ensure the configuration takes effect:
[Tool uses: execute_bash]

> n

I understand you denied the tool request. Let me clarify what we need to do to fix the Q CLI doctor issues:

The `q doctor` command found two problems:
1. `~/.local/bin` is not in your PATH
2. The Q CLI shell integration isn't properly configured

To resolve these issues, you have a few options:

**Option 1: Restart your terminal**
- Close your current terminal window and open a new one
- Then run `q doctor` again to see if the PATH changes took effect

**Option 2: Manual PATH export**
- Run `export PATH="$HOME/.local/bin:$PATH"` in your current session
- Then run `q doctor` to check

**Option 3: Check what Q CLI expects**
- We could examine the Q CLI shell integration files to understand exactly what configuration it needs

Which approach would you prefer to take to resolve the doctor issues?
[Tool uses: none]

> q issue

[Tool uses: execute_bash]

> y

The `q issue` command requires an interactive terminal. You can run it directly from your terminal outside of this chat session to open the GitHub issue template for reporting Q CLI bugs or feature requests.

Alternatively, you can manually visit the Q CLI GitHub repository at https://github.com/aws/amazon-q-developer-cli to create an issue about the doctor command problems we encountered.
[Tool uses: none]

> How do I export the issue directly to the issue?

[Tool uses: report_issue]

(...truncated)
```

### Steps to reproduce

1. Run `q doctor`
2. Add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc before Q CLI post integration
3. Source ~/.zshrc or restart terminal
4. Run `q doctor` again - issue persists

### Environment

```yaml

[q-details]
version = "1.15.0"
hash = "a8a0426eaff32ac9b1599ca1b1f1881ffd16054d"
date = "2025-09-02T17:15:25.464923Z (22d ago)"

[system-info]
os = "macOS 15.7.0 (24G222)"
chip = "Apple M2 Pro"
total-cores = 12
memory = "32.00 GB"

[environment]
cwd = "/Users/USER"
cli-path = "/Users/USER"
install-method = "toolbox"

[env-vars]
PATH = "/Users/USER/.toolbox/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin"
SHELL = "/bin/zsh"
TERM = "xterm-256color"
__CFBundleIdentifier = "com.apple.Terminal"

[chat-settings]

[chat-trusted_tools]
fs_read=trusted

[chat-failed_request_ids]
none

[chat-context]
current_profile=q_cli_default
profile_context=
AmazonQ.md
README.md
.amazonq/rules/**/*.md

files=none
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.