---
globs: src/cli/**/*.ts
---
# CLI Development Patterns
## Commander.js Integration
This project uses Commander.js for CLI functionality with subcommands.
### CLI Structure
- **Main CLI**: [src/cli/xhs-cli.ts](mdc:src/cli/xhs-cli.ts) - Command-line interface entry point
- **Subcommands**: Authentication, browser management, feeds, search, publishing, MCP server
### Command Pattern
```typescript
program
.command('subcommand')
.description('Command description')
.option('-o, --option <value>', 'Option description', 'default')
.action(async (options) => {
try {
// Command implementation
const result = await service.method(options);
console.log(JSON.stringify(result, null, 2));
} catch (error) {
console.error('Error:', error.message);
process.exit(1);
}
});
```
## Available Commands
### Authentication Commands
- `login [--timeout <seconds>]` - Login to XiaoHongShu
- `logout` - Logout from XiaoHongShu
- `status` - Check authentication status
### Browser Commands
- `browser [--with-deps]` - Install/check browser dependencies
### Discovery Commands
- `feeds [-b <browser-path>]` - Get recommended feeds
- `search -k <keyword> [-b <browser-path>]` - Search for content
- `note-detail --feed-id <id> --xsec-token <token> [-b <browser-path>]` - Get note details
### Interaction Commands
- `comment --feed-id <id> --xsec-token <token> -n <note> [-b <browser-path>]` - Comment on note
### Publishing Commands
- `publish -t <title> -c <content> -i <images> --tags <tags> [-b <browser-path>]` - Publish note
### MCP Server Commands
- `mcp [--mode <stdio|http>] [--port <port>]` - Start MCP server
## Error Handling
### CLI Error Pattern
```typescript
try {
// Command implementation
} catch (error) {
if (error instanceof ValidationError) {
console.error('Validation error:', error.message);
} else if (error instanceof AuthenticationError) {
console.error('Authentication error:', error.message);
} else {
console.error('Unexpected error:', error.message);
}
process.exit(1);
}
```
### Exit Codes
- **0**: Success
- **1**: General error
- **2**: Validation error
- **3**: Authentication error
## Output Format
### JSON Output
- **Success**: Pretty-printed JSON with operation results
- **Error**: Error message with context
- **Status**: Structured status information
### Example Output
```json
{
"success": true,
"data": {
"feeds": [...],
"count": 10
},
"operation": "get_feeds"
}
```
## Environment Variables
### Debugging
- `XHS_ENABLE_LOGGING=true` - Enable debug logging
- `XHS_LOG_LEVEL=DEBUG` - Set log level
### Browser Configuration
- `XHS_HEADLESS=false` - Run browser in visible mode
- `XHS_BROWSER_TIMEOUT=60000` - Set browser timeout
## MCP Server Integration
### Stdio Mode
- **No console output** - Only MCP protocol messages
- **Silent operation** - No logging to stdout/stderr
- **Protocol compliance** - Follow MCP stdio transport spec
### HTTP Mode
- **Console logging allowed** - Can log to console
- **Port configuration** - Default port 3000, configurable
- **Health checks** - `/health` endpoint for monitoring
