Redesign @guidepup/setup CLI to support subcommands and future extensibility

[cmorten]

Summary

The @guidepup/setup CLI has gradually become responsible for more than just environment configuration. As Guidepup grows to support installing and managing screen readers, the current flat command structure no longer scales well.

This issue proposes restructuring the CLI around subcommands, similar to the Playwright CLI, making it easier to discover functionality and extend in the future.

Note: this will also require updates to @guidepup/setup-action and @guidepup/guidepup to support the new installation location behaviours, new env var, and the potential for a range of screen reader versions installed.

Motivation

Today the CLI primarily performs environment setup, but we also want it to be responsible for installing screen readers (starting with NVDA).

Instead of introducing additional top-level flags, we should move to a command-based interface that groups related functionality and leaves room for future capabilities.

For users already familiar with Playwright, the CLI should feel immediately recognisable.

Proposed CLI

# Environment setup
guidepup setup

# Install screen readers
guidepup install
guidepup install nvda

# Display installed versions
guidepup list

# Update installed screen readers
guidepup update
guidepup update nvda

# Remove installed screen readers
guidepup uninstall nvda

# Show CLI version
guidepup --version

# Help
guidepup --help
guidepup install --help

Initial scope

setup

Responsible for configuring the local environment required by Guidepup.

This largely maps to the existing CLI behaviour.

Examples:

guidepup setup

install

Downloads and installs supported screen readers.

Initially this would support:

• NVDA

Potential future additions:

• JAWS (where licensing permits)
• Orca
• Other supported screen readers

Examples:

guidepup install
guidepup install nvda

Where no screen reader is specified, the CLI should install the recommended/default screen reader(s) for the current platform.

Installation location

As part of introducing the install commands we should revisit how downloaded screen readers are stored.

Today NVDA is downloaded into a temp directory that is referenced in a registry key. Instead we should adopt a cache layout similar to Playwright, where downloaded screen readers are stored in a predictable, user-level cache directory appropriate for each OS. This has several advantages:

• Downloads persist across projects
• Multiple projects can share a single installation
• CI environments can cache downloads more effectively
• The storage location aligns with established developer tooling
• Reduces complexity dealing with the windows registry, just file system behaviours

The default cache location should follow platform conventions (TBC):

• Windows: %USERPROFILE%\AppData\Local\guidepup
• macOS: ~/Library/Caches/guidepup
• Linux: ~/.cache/guidepup

Configurable cache location

Like Playwright, the download/cache location should be configurable via an environment variable.

This allows users and CI systems to:

• share downloads across jobs
• place installations on larger or faster volumes
• use ephemeral or mounted cache locations
• manage installations centrally

GUIDEPUP_INSTALL_PATH=/opt/guidepup guidepup install

## Inspiration

The design intentionally mirrors the Playwright CLI where appropriate:

playwright install
playwright install chromium
playwright uninstall
playwright install-deps

The goal is not to copy Playwright exactly, but to provide a familiar, predictable developer experience using battle-tested patterns.