fh-cli 0.1.6

Quickly scaffold FastHTML apps!

FastHTML CLI

Fastest way to scaffold FastHTML apps!

📦 Package Name Change: This package was previously named fh-init but has been renamed to fh-cli for consistency. Both commands (fh-cli and fh-init) work during the transition period. We recommend using fh-cli going forward.

Usage

To create a new FastHTML application, use the fh-cli command. Make sure uv is installed before running uvx:

uvx fh-cli [OPTIONS] NAME

Arguments

• NAME: The name of your FastHTML application (required).

Options

• --template, -tp TEXT: The name of the FastHTML template to use (default: base).
• --reload, -r: Enable live reload.
• --pico, -p: Enable Pico CSS (default: True).
• --uv / --no-uv: Use uv to manage project dependencies (default: uv).
• --tailwind, -t: Enable Tailwind CSS.
• --deps, -d TEXT: Space-separated list of Python dependencies to add (e.g., pandas numpy requests).
• --gallery, -g TEXT: Use a FastHTML Gallery example (e.g., todo_series/beginner). When used, other template options are ignored.
• --version: Show version and exit.
• --install-completion: Install tab completion for the current shell (run once to enable auto-completion).
• --show-completion: Show completion script to copy or customize the installation.
• --help: Show the help message and exit.

Examples

# Create a basic app
uvx fh-cli my_awesome_app

# Create an app with live reload and Tailwind CSS
uvx fh-cli my_awesome_app --reload --tailwind

# Create an app with additional Python dependencies
uvx fh-cli data_app --deps "pandas numpy matplotlib"

# Create an app from the FastHTML Gallery
uvx fh-cli my-todo --gallery todo_series/beginner
uvx fh-cli my-viz --gallery visualizations/observable_plot

Then to run the FastHTML app:

cd my_awesome_app
uv run main.py

Shell Completion

For a better CLI experience, you can enable tab completion:

# Install completion for your current shell (run once)
fh-cli --install-completion

# After installation, you can use tab completion
fh-cli <Tab>          # Shows available commands and options
fh-cli --<Tab>        # Shows all available flags

FastHTML Gallery Integration

Bootstrap your projects with real-world examples from the official FastHTML Gallery:

# Browse examples at https://gallery.fastht.ml/
# Use the format: category/example_name

# Todo applications
uvx fh-cli my-todo --gallery todo_series/beginner

# Data visualizations  
uvx fh-cli my-charts --gallery visualizations/observable_plot

# Interactive applications
uvx fh-cli my-app --gallery applications/csv_editor

Gallery Features:

• Complete Examples: Get fully working FastHTML applications instantly
• Auto Dependencies: Required packages automatically added to pyproject.toml
• No Modifications: Gallery code copied exactly as-is for authentic examples
• Exclusive Mode: When using --gallery, other template options (--tailwind, --deps, etc.) are ignored

Available Categories:

• applications/ - Full-featured apps (csv_editor, tic_tac_toe, etc.)
• todo_series/ - Todo app examples of varying complexity
• visualizations/ - Data visualization examples
• widgets/ - Reusable UI components
• svg/ - SVG and graphics examples
• dynamic_user_interface_(htmx)/ - Advanced HTMX interactions

Development

Initial Setup

For first-time setup:

1. Activate the virtual environment:

   source .venv/bin/activate
   

2. Install the CLI locally in editable mode:

   uv pip install -e .
   

Quick Development Workflow

After making any changes to code or pyproject.toml:

1. In the CLI root folder, run:

   source .venv/bin/activate && uv pip install -e . --force-reinstall && uv cache clean
   

2. Use the local development CLI from any other folder:

   # Check version
   uvx --from <path-to-local-cli-folder> fh-cli --version
   
   # Create a test project
   uvx --from <path-to-local-cli-folder> fh-cli test-app
   

Troubleshooting

• If uvx shows old version after changes, the single update command above should resolve it
• The --version flag reads from package metadata to ensure version consistency with pyproject.toml

Switching Back to PyPI Version

After local development, you may want to return to using the official PyPI version:

1. Deactivate the development environment:

   deactivate
   

2. Use the official PyPI version:

   # This will automatically use the latest PyPI version
   uvx fh-cli --version
   uvx fh-cli my-app
   

Notes:

• uvx automatically isolates package environments, so your local development doesn't affect the global PyPI version
• The --from <path> flag in development only affects that specific command
• Once you deactivate the virtual environment, uvx fh-cli will use the official PyPI package
• No need to uninstall anything - uvx handles package isolation automatically