README

An interactive TUI (terminal UI) menu for DDEV projects. Run ddev project inside any DDEV project to get a keyboard-navigable menu of your shell scripts.

Features

Scans private/scripts/*.sh for annotated shell scripts
Groups scripts with a two-column layout: menu list on the left, help panel on the right
Displays the DDEV project name as a Figlet title
Confirmation prompt support before executing sensitive scripts
No external TUI framework required at runtime — pure ANSI escape sequences

Requirements

PHP 8.1+
DDEV

Installation

Add this package as a dev dependency to your DDEV project:

composer require --dev rolf-thomas/ddev-project-menu

Then create the DDEV custom command file at .ddev/commands/host/project:

#!/usr/bin/env bash
## Description: Open the interactive project menu
## Usage: project
## Example: ddev project

"$(composer -d "$DDEV_APPROOT" config vendor-dir)/rolf-thomas/ddev-project-menu/bin/ddev-project-menu"

Make it executable:

chmod +x .ddev/commands/host/project

The command runs on the host (not inside the container) — this is required for interactive TTY support.

Usage

ddev project

Navigate with arrow keys, press Enter to run the selected script, q or Esc to quit.

Script annotations

Scripts are included in the menu only if they have a @label annotation. All tags are read from the leading comment block (stops at the first non-comment line):

#!/usr/bin/env bash
# @label       Deploy to staging
# @description Builds assets and syncs files to the staging server.
#              Runs composer install on the remote as well.
# @confirm     true
# @group       Deployment

Tag	Required	Description
`@label`	yes	Short label shown in the menu list
`@description`	no	Help text shown in the right panel (multiple lines supported)
`@group`	no	Group heading; defaults to `Sonstige`
`@confirm`	no	Set to `true` to ask for confirmation before executing

Scripts without @label are silently skipped — useful for helper files like functions.sh or ask.sh that are sourced by other scripts.

Local development

Clone the repository and install dependencies:

composer install

To test against a real DDEV project, add this package as a path repository in the host project's composer.json:

"repositories": {
    "ddev-project-menu": {
        "type": "path",
        "url": "/path/to/ddev-project-menu",
        "options": { "symlink": true }
    }
}

Then run ddev project in that project to test the full TUI interactively.

License

MIT

rolf-thomas / ddev-project-menu

Maintainers

Package info

Statistics

Security