@whyuds/ask-user/README.md

A cross-platform command-line tool and MCP server to show dialog windows and get user input for AI code editors

# AskUser

A cross-platform command-line tool that shows a dialog window to get user input. Works on Windows, macOS, and Linux.

## Features

- 🖥️ Cross-platform support (Windows, macOS, Linux)
- 💬 Simple dialog window interface
- ⌨️ Keyboard shortcuts (Enter to submit, ESC to cancel)
- 🎨 Clean and modern UI
- 📦 Easy to install via npm
- 📝 Multi-line text input support
- 🪟 Minimalist UI with no menu bar or window frame
- 🖱️ Draggable title bar
- ⚡ Ctrl+Enter shortcut for submitting input

## Installation

### Global Installation (Recommended)

```bash
npm install -g @whyuds/ask-user
```

## MCP Server Support

AskUser can be used as an MCP (Model Context Protocol) server for AI code editors like Cursor, Windsurf, and Trae. This allows AI assistants to interact with users during code generation.

### Quick MCP Setup

Add to your AI editor's MCP configuration:

```json
{
  "mcpServers": {
    "ask-user": {
      "command": "npx",
      "args": ["-y", "ask-user-mcp"],
      "env": {}
    }
  }
}
```

For detailed MCP usage instructions, see [MCP-USAGE.md](./MCP-USAGE.md).

### Local Installation

```bash
npm install ask-user
```

## Usage

### Command Line

```bash
# Basic usage
ask --title "Question" --message "What is 1+1?"

# Short form
ask -t "Question" -m "What is 1+1?"

# Only title
ask --title "Please enter your name"

# Only message
ask --message "Enter your response:"

# No parameters (default dialog)
ask

# Multi-line input example
ask --title "Feedback" --message "Please provide your detailed feedback:"
```

### User Interface

- **Multi-line input**: The dialog supports multi-line text input in a resizable textarea
- **Submit**: Click the "Submit" button or press `Ctrl+Enter` to submit your input
- **Cancel**: Click the "Cancel" button, press `Escape`, or click the × button to cancel
- **Drag**: Use the blue title bar to drag the window around

### Programmatic Usage

```javascript
const AskUser = require('ask-user');
const { app } = require('electron');

async function example() {
  const askUser = new AskUser();
  const result = await askUser.showDialog('Question', 'What is your name?');
  console.log('User input:', result);
  app.quit();
}

app.whenReady().then(example);
```

## Options

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--title` | `-t` | Dialog window title | "Please provide your input" |
| `--message` | `-m` | Message to display | "Enter your response below:" |
| `--help` | `-h` | Show help information | - |
| `--version` | `-V` | Show version number | - |

## Examples

### Example 1: Simple Question
```bash
ask --title "Math Question" --message "What is 1+1?"
```

### Example 2: User Information
```bash
ask --title "User Info" --message "Please enter your email address:"
```

### Example 3: Confirmation
```bash
ask --title "Confirmation" --message "Are you sure you want to continue? (yes/no)"
```

## Keyboard Shortcuts

- **Enter**: Submit the input
- **ESC**: Cancel and close the dialog
- **Tab**: Navigate between elements

## Output

The tool outputs the user's input to stdout. If the user cancels or closes the dialog, an empty string is returned.

```bash
$ ask -t "Name" -m "Enter your name:"
John Doe

$ ask -t "Cancelled" -m "This will be cancelled"
# User presses ESC or closes window
# (empty output)
```

## Requirements

- Node.js 14.0.0 or higher
- npm or yarn

## Platform Support

- ✅ Windows 10/11
- ✅ macOS 10.14+
- ✅ Linux (Ubuntu, Debian, CentOS, etc.)

## Development

### Clone and Install

```bash
git clone https://github.com/whyuds/AskUser.git
cd AskUser
npm install
```

### Test Locally

```bash
node bin/ask.js --title "Test" --message "Testing locally"
```

### Publish to npm

```bash
# Login to npm (if not already logged in)
npm login

# Publish the package
npm publish
```

### Test the Package

```bash
# Run the test script
node test.js
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Issues

If you encounter any issues, please report them on the [GitHub Issues](https://github.com/whyuds/AskUser/issues) page.

## Changelog

### v1.0.0
- Initial release
- Cross-platform dialog support
- Command-line interface
- Keyboard shortcuts
- Modern UI design