[TESTING][CLI]: Command-Line Interface, Help Text, and Error Messages

# [TESTING][CLI]: Command-Line Interface, Help Text, and Error Messages

## Goal

Produce a **comprehensive manual test plan** for validating CLI tools provide a good developer experience including accurate help text, clear error messages, correct exit codes, and shell completion.

## Why Now?

CLI is the primary developer interface:

1. **First Interaction**: CLI is often the first touchpoint
2. **Automation**: Scripts depend on consistent behavior
3. **Error Debugging**: Clear errors save debugging time
4. **Discoverability**: Help text enables self-service
5. **Integration**: Shell completion improves productivity

---

## User Stories

<details>
<summary>US-1: Developer - CLI Discovery</summary>

**As a** developer
**I want** comprehensive help text
**So that** I can discover commands without documentation

**Acceptance Criteria:**

```gherkin
Feature: CLI Help

 Scenario: View all commands
 Given I run mcpgateway --help
 Then I should see all available commands
 And each command should have a description
```

</details>

<details>
<summary>US-2: Automation - Exit Codes</summary>

**As a** DevOps engineer
**I want** correct exit codes
**So that** I can script reliable automation

**Acceptance Criteria:**

```gherkin
Feature: Exit Codes

 Scenario: Failed command
 Given I run a command with invalid arguments
 Then the exit code should be non-zero
 And stderr should contain the error
```

</details>

---

## Architecture

```
 CLI STRUCTURE
+------------------------------------------------------------------------+
| |
| mcpgateway |
| ---------- |
| |
| ├── serve # Start the gateway server |
| │ ├── --host # Bind address |
| │ ├── --port # Listen port |
| │ └── --reload # Enable auto-reload |
| │ |
| ├── translate # Stdio to HTTP translation |
| │ ├── --stdio # Command to run |
| │ ├── --port # HTTP port |
| │ └── --sse # Enable SSE mode |
| │ |
| └── utils |
| └── create_jwt_token # Generate JWT token |
| ├── --username # Token subject |
| ├── --secret # Signing key |
| └── --exp # Expiration (minutes) |
| |
+------------------------------------------------------------------------+
```

---

## Test Environment Setup

```bash
# Ensure CLI is installed
pip install -e .

# Verify installation
mcpgateway --version
python -m mcpgateway --version

# Environment for testing
export DATABASE_URL="sqlite:///test.db"
export JWT_SECRET_KEY="test-secret"
```

---

## Manual Test Cases

| Case | Command | Validation | Expected Result |
|------|---------|------------|-----------------|
| CLI-01 | --help | Shows all commands | Accurate help text |
| CLI-02 | --version | Shows version | Correct version |
| CLI-03 | serve | Starts server | Server runs |
| CLI-04 | translate | Stdio translation | Works correctly |
| CLI-05 | create_jwt_token | Token generation | Valid token |
| CLI-06 | Invalid args | Error handling | Clear error |
| CLI-07 | Missing required | Validation | Helpful message |
| CLI-08 | Tab completion | Shell completion | Commands complete |

---

<details>
<summary>CLI-01: Help Text Accuracy</summary>

**Steps:**
```bash
# Main help
mcpgateway --help

# Command-specific help
mcpgateway serve --help
mcpgateway translate --help
python -m mcpgateway.utils.create_jwt_token --help
```

**Validation Checklist:**
| Command | Has Description | Lists All Options | Examples Present |
|---------|-----------------|-------------------|------------------|
| mcpgateway | | | |
| serve | | | |
| translate | | | |
| create_jwt_token | | | |

**Check for:**
- [ ] All commands listed
- [ ] Each command has description
- [ ] All options documented
- [ ] Default values shown
- [ ] Required options marked
- [ ] Examples provided (if applicable)

**Expected Result:**
- Help text is accurate and complete
- Options match actual behavior
- Descriptions are helpful

</details>

<details>
<summary>CLI-02: Version Output</summary>

**Steps:**
```bash
# Check version
mcpgateway --version
python -m mcpgateway --version

# Verify matches package
pip show mcpgateway | grep Version
```

**Expected Result:**
- Version displayed correctly
- Matches installed package version

</details>

<details>
<summary>CLI-03: Serve Command</summary>

**Steps:**
```bash
# Start with defaults
mcpgateway serve &
PID=$!
sleep 5
curl -s http://localhost:8000/health | jq .
kill $PID

# Start with custom options
mcpgateway serve --host 127.0.0.1 --port 9999 &
PID=$!
sleep 5
curl -s http://127.0.0.1:9999/health | jq .
kill $PID

# Start with reload (development)
mcpgateway serve --reload &
PID=$!
sleep 5
# Modify a file and verify reload
kill $PID
```

**Expected Result:**
- Server starts with default options
- Custom host/port respected
- Reload mode works correctly

</details>

<details>
<summary>CLI-04: Translate Command</summary>

**Steps:**
```bash
# Start stdio translation
mcpgateway translate --stdio "uvx mcp-server-time" --port 9000 &
PID=$!
sleep 5

# Test HTTP endpoint
curl -s -X POST http://localhost:9000/mcp/http \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

# Test SSE endpoint
curl -s http://localhost:9000/sse

kill $PID
```

**Expected Result:**
- Stdio server wrapped in HTTP
- MCP protocol works through translation
- SSE endpoint available

</details>

<details>
<summary>CLI-05: Token Generation</summary>

**Steps:**
```bash
# Generate token with defaults
python -m mcpgateway.utils.create_jwt_token \
 --username admin@example.com \
 --secret test-secret

# Generate with expiration
python -m mcpgateway.utils.create_jwt_token \
 --username admin@example.com \
 --secret test-secret \
 --exp 60

# Generate non-expiring (exp=0)
python -m mcpgateway.utils.create_jwt_token \
 --username admin@example.com \
 --secret test-secret \
 --exp 0
```

**Validation:**
```bash
# Decode and verify token
TOKEN=$(python -m mcpgateway.utils.create_jwt_token --username admin --secret test-secret)
echo $TOKEN | cut -d. -f2 | base64 -d | jq .

# Use token
curl -s http://localhost:8000/api/users/me \
 -H "Authorization: Bearer $TOKEN"
```

**Expected Result:**
- Token generated successfully
- Token contains correct claims
- Expiration set correctly
- Token works for authentication

</details>

<details>
<summary>CLI-06: Invalid Arguments</summary>

**Steps:**
```bash
# Unknown option
mcpgateway serve --unknown-option
echo "Exit code: $?"

# Invalid value
mcpgateway serve --port abc
echo "Exit code: $?"

# Unknown command
mcpgateway unknowncommand
echo "Exit code: $?"
```

**Expected Results:**
| Scenario | Exit Code | Error Message |
|----------|-----------|---------------|
| Unknown option | 2 | "Unknown option" |
| Invalid value | 2 | "Invalid value" |
| Unknown command | 2 | "No such command" |

**Expected Result:**
- Non-zero exit code for all errors
- Error written to stderr
- Error message is descriptive

</details>

<details>
<summary>CLI-07: Missing Required Arguments</summary>

**Steps:**
```bash
# Missing required --secret
python -m mcpgateway.utils.create_jwt_token --username admin
echo "Exit code: $?"

# Missing --stdio for translate
mcpgateway translate --port 9000
echo "Exit code: $?"
```

**Expected Result:**
- Error message names missing argument
- Suggests correct usage
- Non-zero exit code

</details>

<details>
<summary>CLI-08: Shell Completion</summary>

**Setup (Bash):**
```bash
# Generate completion script
mcpgateway --install-completion bash
# Or manually source if available
source <(mcpgateway completion bash)
```

**Setup (Zsh):**
```bash
mcpgateway --install-completion zsh
# Or add to .zshrc
```

**Test Completion:**
```bash
# Type and press Tab
mcpgateway <TAB>
# Should show: serve, translate, ...

mcpgateway serve --<TAB>
# Should show: --host, --port, --reload, ...
```

**Expected Result:**
- Completion script available
- Commands complete correctly
- Options complete with descriptions

</details>

---

## Exit Code Reference

| Code | Meaning | Examples |
|------|---------|----------|
| 0 | Success | Command completed |
| 1 | General error | Runtime error |
| 2 | Usage error | Invalid arguments |
| 3 | Configuration error | Missing env vars |

---

## Test Matrix

| Command | Scenario | Exit Code | Output Location |
|---------|----------|-----------|-----------------|
| serve | Success | 0 (on SIGTERM) | stdout |
| serve | Bind error | 1 | stderr |
| translate | Success | 0 (on SIGTERM) | stdout |
| translate | Missing --stdio | 2 | stderr |
| create_jwt_token | Success | 0 | stdout (token) |
| create_jwt_token | Missing --secret | 2 | stderr |
| --help | Always | 0 | stdout |
| --version | Always | 0 | stdout |

---

## Success Criteria

- [ ] All CLI commands documented in --help
- [ ] Help text matches actual behavior
- [ ] Error messages are clear and actionable
- [ ] Exit codes are correct (0=success, non-zero=error)
- [ ] Shell completion available for Bash/Zsh
- [ ] Version output matches installed version
- [ ] All options work as documented

---

## Related Files

- `mcpgateway/__main__.py` - CLI entry point
- `mcpgateway/cli.py` - Command definitions
- `mcpgateway/utils/create_jwt_token.py` - Token utility
- `mcpgateway/translate.py` - Translation command

---

## Related Issues

- #2434 - Configuration
- #2475 - Deployment
- #2483 - Documentation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[TESTING][CLI]: Command-Line Interface, Help Text, and Error Messages #2481

[TESTING][CLI]: Command-Line Interface, Help Text, and Error Messages

Goal

Why Now?

User Stories

Architecture

Test Environment Setup

Manual Test Cases

Exit Code Reference

Test Matrix

Success Criteria

Related Files

Related Issues

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Case	Command	Validation	Expected Result
CLI-01	--help	Shows all commands	Accurate help text
CLI-02	--version	Shows version	Correct version
CLI-03	serve	Starts server	Server runs
CLI-04	translate	Stdio translation	Works correctly
CLI-05	create_jwt_token	Token generation	Valid token
CLI-06	Invalid args	Error handling	Clear error
CLI-07	Missing required	Validation	Helpful message
CLI-08	Tab completion	Shell completion	Commands complete

Scenario	Exit Code	Error Message
Unknown option	2	"Unknown option"
Invalid value	2	"Invalid value"
Unknown command	2	"No such command"

Code	Meaning	Examples
0	Success	Command completed
1	General error	Runtime error
2	Usage error	Invalid arguments
3	Configuration error	Missing env vars

Command	Scenario	Exit Code	Output Location
serve	Success	0 (on SIGTERM)	stdout
serve	Bind error	1	stderr
translate	Success	0 (on SIGTERM)	stdout
translate	Missing --stdio	2	stderr
create_jwt_token	Success	0	stdout (token)
create_jwt_token	Missing --secret	2	stderr
--help	Always	0	stdout
--version	Always	0	stdout

[TESTING][CLI]: Command-Line Interface, Help Text, and Error Messages #2481

Description

[TESTING][CLI]: Command-Line Interface, Help Text, and Error Messages

Goal

Why Now?

User Stories

Architecture

Test Environment Setup

Manual Test Cases

Exit Code Reference

Test Matrix

Success Criteria

Related Files

Related Issues

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions