npx-ui -- Universal Web UI for CLI Packages

Automatically generate a web-based UI for any CLI tool. Point it at an npm package and get a form-driven interface in your browser -- no code changes to the target CLI required.

Quick Start

npx npx-ui run <package-name>

For example:

npx npx-ui run eslint

This will introspect the CLI, generate a web form, and open your browser to http://localhost:3000.

CLI Options

| Option | Description | Default | |---|---|---| | --port <number> | Port to listen on | 3000 | | --no-open | Do not auto-open the browser | false | | --no-timeout | Disable the 30-minute process timeout | false |

How It Works

1. Detect -- npx-ui introspects the target package using a multi-strategy fallback chain: webui.config.json > Commander.js reflection > --help output parsing.
2. Generate -- Discovered commands, arguments, and options are converted to JSON Schema, which drives a dynamic form UI in the browser.
3. Serve -- An Express server hosts the UI and a WebSocket endpoint. Form submissions spawn the CLI as a child process (shell: false), streaming stdout/stderr back to the browser in real time.

Supported CLI Frameworks

• Commander.js -- Full reflection via monkey-patching parse(). Commands, options, arguments, choices, and defaults are all captured.
• Any CLI with --help -- Universal fallback parser that extracts options, arguments, and subcommands from standard help output.
• Custom config -- Drop a webui.config.json in your package root for full control.

webui.config.json Example

{
  "commands": [
    {
      "name": "build",
      "description": "Build the project",
      "arguments": [
        { "name": "target", "description": "Build target", "type": "string", "required": true }
      ],
      "options": [
        { "name": "watch", "alias": "w", "description": "Watch mode", "type": "boolean" },
        { "name": "output", "alias": "o", "description": "Output dir", "type": "file", "required": true }
      ]
    }
  ]
}

API Reference

All endpoints are served on http://localhost:<port> and restricted to localhost connections only.

| Method | Endpoint | Description | |---|---|---| | GET | /api/package | Package metadata (name, version, config source) | | GET | /api/commands | List of commands with JSON Schema definitions | | POST | /api/execute | Start a command execution. Body: { command, formData } | | GET | /api/executions | List active and completed executions | | DELETE | /api/executions/:id | Kill a running execution |

POST /api/execute

Request body:

{
  "command": "build",
  "formData": {
    "_arg_target": "production",
    "watch": true,
    "output": "./dist"
  }

Response (201):

{
  "executionId": "uuid",
  "status": "running",
  "wsUrl": "ws://localhost:3000/ws?id=uuid"
}

WebSocket Protocol

Connect to ws://localhost:<port>/ws?id=<executionId> to receive real-time output.

Server to client messages:

| Type | Fields | Description | |---|---|---| | stdout | data, ts | Standard output chunk | | stderr | data, ts | Standard error chunk | | status | executionId, status | Process status change | | done | executionId, exitCode, duration, signal | Process completed |

Client to server messages:

| Type | Fields | Description | |---|---|---| | stdin | data | Send input to process (reserved) | | kill | signal? | Kill the running process |

Security Model

npx-ui implements a 6-layer defense model (localhost only):

1. 127.0.0.1 binding -- Server binds to loopback only, never 0.0.0.0.
2. Origin validation -- HTTP and WebSocket connections validate Origin/Host headers against a localhost allowlist.
3. CSP headers -- Content-Security-Policy restricts scripts, styles, and connections to self and localhost WebSocket.
4. Command whitelist -- Only commands discovered during introspection can be executed. Arbitrary commands are rejected.
5. Argument sanitization -- Shell metacharacters (;, |, &, `, $(), etc.) are stripped from all argument values.
6. No shell execution -- All processes are spawned with shell: false via child_process.spawn, passing arguments as arrays.

Development

Build

npm install
npm run build          # Compile TypeScript
npm run build:client   # Bundle client HTML

Test

npm run build
npm test

Project Structure

src/
  index.ts              # Entry point, orchestration
  cli.ts                # CLI argument parsing (Commander.js)
  core/
    types.ts            # Domain types
    schema-parser.ts    # Multi-strategy CLI introspection
    process-manager.ts  # Child process lifecycle management
  server/
    app.ts              # Express app setup, security middleware
    routes.ts           # API route handlers
    websocket.ts        # WebSocket server and event bridging
  client/               # React UI (bundled to client.html)

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and add tests
4. Run the test suite: npm test
5. Submit a pull request

License

MIT