bitp 1.0.6__py3-none-any.whl

bitbake_project/cli.py

@@ -0,0 +1,1580 @@
+#!/usr/bin/env python3
+# PYTHON_ARGCOMPLETE_OK
+#
+# Copyright (C) 2025 Bruce Ashfield <bruce.ashfield@gmail.com>
+#
+# SPDX-License-Identifier: GPL-2.0-only
+#
+"""
+CLI entry point for bit.
+
+Handles argument parsing and command dispatch.
+"""
+
+import argparse
+import json
+import os
+import signal
+import subprocess
+import sys
+from typing import Dict, List, Optional, Set, Tuple
+
+from .core import Colors, fzf_expandable_menu, parse_help_options
+from .commands import fzf_available
+
+# Try to import argcomplete for tab completion
+try:
+    import argcomplete
+    from argcomplete.completers import SuppressCompleter
+    HAS_ARGCOMPLETE = True
+
+    class RepoCompleter:
+        """Complete repo names from bblayers.conf."""
+        def __init__(self, include_edit=False):
+            self.include_edit = include_edit
+
+        def __call__(self, prefix, parsed_args, **kwargs):
+            try:
+                completions = []
+                # Add 'edit' as a valid option for config command
+                if self.include_edit and "edit".startswith(prefix):
+                    completions.append("edit")
+
+                # Try to get repos for completion
+                bblayers = getattr(parsed_args, 'bblayers', None)
+                path = bblayers or "conf/bblayers.conf"
+                if not os.path.exists(path):
+                    path = "build/conf/bblayers.conf"
+                if not os.path.exists(path):
+                    return completions
+                # Quick parse for completion
+                with open(path) as f:
+                    content = f.read()
+                import re
+                # Match both quoted and unquoted paths
+                paths = re.findall(r'"([^"]+)"', content)
+                paths += re.findall(r'^\s*(/[^\s\\]+)', content, re.MULTILINE)
+                repos = set()
+                for p in paths:
+                    if '/' in p and '${' not in p and os.path.isdir(p):
+                        try:
+                            toplevel = subprocess.check_output(
+                                ["git", "-C", p, "rev-parse", "--show-toplevel"],
+                                stderr=subprocess.DEVNULL, text=True
+                            ).strip()
+                            # Try to get custom display name first
+                            try:
+                                display = subprocess.check_output(
+                                    ["git", "-C", toplevel, "config", "--get", "bit.display-name"],
+                                    stderr=subprocess.DEVNULL, text=True
+                                ).strip()
+                            except:
+                                # Fall back to deriving from origin URL or basename
+                                try:
+                                    url = subprocess.check_output(
+                                        ["git", "-C", toplevel, "config", "--get", "remote.origin.url"],
+                                        stderr=subprocess.DEVNULL, text=True
+                                    ).strip()
+                                    display = os.path.basename(url.rstrip('/'))
+                                    if display.endswith('.git'):
+                                        display = display[:-4]
+                                except:
+                                    display = os.path.basename(toplevel)
+                            repos.add(display)
+                        except:
+                            pass
+                completions.extend([r for r in repos if r.lower().startswith(prefix.lower())])
+                return completions
+            except:
+                return []
+
+    class LayerCompleter:
+        """Complete layer names from bblayers.conf."""
+        def __call__(self, prefix, parsed_args, **kwargs):
+            try:
+                bblayers = getattr(parsed_args, 'bblayers', None)
+                path = bblayers or "conf/bblayers.conf"
+                if not os.path.exists(path):
+                    path = "build/conf/bblayers.conf"
+                if not os.path.exists(path):
+                    return []
+                with open(path) as f:
+                    content = f.read()
+                import re
+                # Match both quoted and unquoted paths
+                paths = re.findall(r'"([^"]+)"', content)
+                paths += re.findall(r'^\s*(/[^\s\\]+)', content, re.MULTILINE)
+                layers = []
+                for p in paths:
+                    if '/' in p and '${' not in p and os.path.isdir(p):
+                        layers.append(os.path.basename(p))
+                return [l for l in layers if l.lower().startswith(prefix.lower())]
+            except:
+                return []
+
+except ImportError:
+    HAS_ARGCOMPLETE = False
+
+
+# =============================================================================
+# SINGLE SOURCE OF TRUTH FOR ALL COMMANDS
+# =============================================================================
+# Add new commands/subcommands here. Format:
+#   (command, description, [subcommands])
+# where subcommands is a list of (subcommand, description) tuples.
+#
+# This list is used by:
+#   - Interactive command menu (bit with no args)
+#   - Help browser (bit help)
+#   - Bash completion
+# =============================================================================
+COMMAND_TREE = [
+    ("branch", "View and switch branches across repos", []),
+    ("config", "View and configure repo/layer settings", []),
+    ("deps", "Show layer and recipe dependencies", [
+        ("deps layers", "Show layer dependency tree"),
+        ("deps recipe", "Show recipe dependency tree"),
+    ]),
+    ("export", "Export patches from layer repos", [
+        ("export prep", "Prepare commits for export (reorder/group)"),
+    ]),
+    ("explore", "Interactively explore commits in layer repos", []),
+    ("fragments", "Browse and manage OE configuration fragments", [
+        ("fragments list", "List all available fragments"),
+        ("fragments enable", "Enable a fragment"),
+        ("fragments disable", "Disable a fragment"),
+        ("fragments show", "Show fragment content"),
+    ]),
+    ("help", "Browse help for all commands", []),
+    ("init", "Initialize/setup OE/Yocto build environment", [
+        ("init shell", "Start a shell with build environment pre-sourced"),
+        ("init clone", "Show or clone core Yocto/OE repositories"),
+    ]),
+    ("projects", "Manage multiple project directories", [
+        ("projects add", "Add a project directory"),
+        ("projects remove", "Remove a project from list"),
+        ("projects list", "List all registered projects"),
+    ]),
+    ("recipes", "Search and browse BitBake recipes", []),
+    ("repos", "List layer repos", [
+        ("repos status", "Show one-liner status for each repo"),
+    ]),
+    ("search", "Search OpenEmbedded Layer Index for layers", []),
+    ("status", "Show local commit summary for layer repos", []),
+    ("update", "Update git repos referenced by layers in bblayers.conf", []),
+]
+
+# =============================================================================
+# COMMAND CATEGORIES FOR MENU GROUPING
+# =============================================================================
+# Define categories and which commands belong to each.
+# CATEGORY_ORDER determines display order in the menu.
+# =============================================================================
+COMMAND_CATEGORIES = {
+    "git": ("Git/Repository", ["explore", "branch", "status", "update", "repos", "export"]),
+    "config": ("Configuration", ["config", "fragments", "init", "projects"]),
+    "discovery": ("Discovery", ["recipes", "deps", "search"]),
+    "help": ("Help", ["help"]),
+}
+
+CATEGORY_ORDER = ["git", "config", "discovery", "help"]
+
+# Commands grouped by interaction style (alternative grouping)
+INTERACTION_CATEGORIES = {
+    "interactive": ("Interactive (fzf browsers)", ["explore", "branch", "recipes", "fragments", "deps", "search", "projects", "help"]),
+    "output": ("Output & Exit", ["status", "update", "repos", "config", "init", "export"]),
+}
+
+INTERACTION_ORDER = ["interactive", "output"]
+
+
+def get_menu_sort_mode(defaults_file: str = ".bit.defaults") -> str:
+    """
+    Get the menu sort mode from defaults file.
+
+    Returns:
+        Sort mode: "category" (default), "alpha", or "interactive"
+    """
+    try:
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+            mode = data.get("menu_sort", "category")
+            if mode in ("category", "alpha", "interactive"):
+                return mode
+    except (json.JSONDecodeError, OSError):
+        pass
+    return "category"
+
+
+def sort_commands_by_mode(
+    commands: List[Tuple[str, str, List[Tuple[str, str]]]],
+    mode: str,
+) -> Tuple[List[Tuple[str, str, List[Tuple[str, str]]]], Optional[Dict[str, str]]]:
+    """
+    Sort/group commands based on the specified mode.
+
+    Args:
+        commands: List of (cmd, description, subcommands) tuples
+        mode: "alpha", "category", or "interactive"
+
+    Returns:
+        Tuple of (sorted_commands, categories_dict) where categories_dict maps
+        command names to their category headers (or None for alpha mode).
+    """
+    if mode == "alpha":
+        return sorted(commands, key=lambda x: x[0]), None
+
+    # Build command lookup
+    cmd_lookup = {cmd: (cmd, desc, subs) for cmd, desc, subs in commands}
+
+    if mode == "interactive":
+        categories = INTERACTION_CATEGORIES
+        order = INTERACTION_ORDER
+    else:  # category (default)
+        categories = COMMAND_CATEGORIES
+        order = CATEGORY_ORDER
+
+    sorted_commands: List[Tuple[str, str, List[Tuple[str, str]]]] = []
+    cmd_to_category: Dict[str, str] = {}
+
+    for cat_key in order:
+        if cat_key not in categories:
+            continue
+        cat_label, cat_cmds = categories[cat_key]
+        first_in_category = True
+        for cmd_name in cat_cmds:
+            if cmd_name in cmd_lookup:
+                if first_in_category:
+                    cmd_to_category[cmd_name] = cat_label
+                    first_in_category = False
+                sorted_commands.append(cmd_lookup[cmd_name])
+
+    # Add any commands not in any category at the end
+    categorized = set()
+    for cat_key in order:
+        if cat_key in categories:
+            categorized.update(categories[cat_key][1])
+    for cmd, desc, subs in commands:
+        if cmd not in categorized:
+            sorted_commands.append((cmd, desc, subs))
+
+    return sorted_commands, cmd_to_category
+
+# Flatten for legacy COMMANDS list (used by some completers)
+COMMANDS = [(cmd, desc) for cmd, desc, _ in COMMAND_TREE]
+for cmd, desc, subs in COMMAND_TREE:
+    for subcmd, subdesc in subs:
+        COMMANDS.append((subcmd, subdesc))
+
+
+def build_parser() -> Tuple[argparse.ArgumentParser, Dict]:
+    """Build the argument parser with all subcommands."""
+    parser = argparse.ArgumentParser(
+        description="Tools for BitBake projects",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "--completion",
+        action="store_true",
+        help="Show bash completion setup instructions",
+    )
+    # Global options available to all subcommands
+    parser.add_argument(
+        "--bblayers",
+        default=None,
+        help="Path to bblayers.conf (auto-detects conf/bblayers.conf or build/conf/bblayers.conf if omitted)",
+    )
+    parser.add_argument(
+        "--defaults-file",
+        default=".bit.defaults",
+        help="Path to per-repo default actions file",
+    )
+    parser.add_argument(
+        "--all", "-a",
+        action="store_true",
+        help="Discover all layers/repos (slower, finds unconfigured layers)",
+    )
+    subparsers = parser.add_subparsers(dest="command", metavar="action", title="commands")
+
+    # ---------- update ----------
+    update = subparsers.add_parser(
+        "update",
+        aliases=["u"],
+        help="Update git repos referenced by layers in bblayers.conf",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    update.add_argument("repo", nargs="?", help="Specific repo to update (by name, index, or path)")
+    update.add_argument("--dry-run", action="store_true", help="Show the commands that would run without executing them")
+    update.add_argument("--resume", action="store_true", help="Resume from previous run using the resume file")
+    update.add_argument(
+        "--resume-file",
+        default=".bitbake-layers-update.resume",
+        help="Path to resume state file",
+    )
+    update.add_argument(
+        "--plain",
+        action="store_true",
+        help="Use text-based prompts instead of fzf",
+    )
+
+    # ---------- status ----------
+    status = subparsers.add_parser(
+        "status",
+        help="Show local commit summary for layer repos (alias for 'explore --status')",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    status.add_argument("--max-commits", type=int, default=10, help="Max commits to show with -v")
+    status.add_argument(
+        "-v", "--verbose",
+        action="count",
+        default=0,
+        help="Increase verbosity: -v shows commits (limited), -vv shows all commits",
+    )
+    status.add_argument(
+        "--fetch",
+        action="store_true",
+        help="Fetch from origin before checking status (shows accurate upstream changes)",
+    )
+
+    # ---------- repos ----------
+    repos = subparsers.add_parser(
+        "repos",
+        help="List layer repos",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    repos_sub = repos.add_subparsers(dest="repos_command", metavar="command")
+
+    repos_status = repos_sub.add_parser(
+        "status",
+        help="Show one-liner status: commit counts, branch, clean/dirty",
+    )
+    repos_status.add_argument(
+        "--fetch",
+        action="store_true",
+        help="Fetch from origin before checking",
+    )
+
+    # ---------- init ----------
+    init = subparsers.add_parser(
+        "init",
+        help="Initialize/setup OE/Yocto build environment",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Subcommands:
+  (none)    Show the source command for oe-init-build-env
+  shell     Start a new shell with build environment pre-sourced
+  clone     Clone core Yocto/OE repositories for a new project
+
+Examples:
+  # Show the source command to set up build environment
+  bit init
+
+  # Start a shell ready to run bitbake commands
+  bit init shell
+
+  # Clone core repos then show setup command
+  bit init clone --execute
+  bit init clone -b scarthgap --execute
+""",
+    )
+    init_subparsers = init.add_subparsers(dest="init_command")
+
+    # Default behavior (no subcommand): show source command
+    init.add_argument(
+        "--layers-dir",
+        default="layers",
+        help="Directory containing layers (relative to current dir)",
+    )
+
+    # init shell subcommand
+    init_shell = init_subparsers.add_parser(
+        "shell",
+        help="Start a shell with build environment pre-sourced",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Start a new interactive shell with the OE/Yocto build environment already
+sourced. You can immediately run bitbake commands without manual setup.
+
+The shell prompt will show "(oe)" to indicate the environment is active.
+
+Examples:
+  # Start a shell ready for bitbake
+  bit init shell
+
+  # With custom layers directory
+  bit init shell --layers-dir my-layers
+""",
+    )
+    init_shell.add_argument(
+        "--layers-dir",
+        default="layers",
+        help="Directory containing layers (relative to current dir)",
+    )
+
+    # init clone subcommand
+    init_clone = init_subparsers.add_parser(
+        "clone",
+        help="Show or clone core Yocto/OE repositories",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Clone the three core repositories needed for a Yocto/OE build:
+  - bitbake: The build engine
+  - openembedded-core: Core metadata and recipes
+  - meta-yocto: Yocto Project reference distribution (poky)
+
+Examples:
+  # Show clone commands without executing
+  bit init clone
+
+  # Clone repos into layers/ directory
+  bit init clone --execute
+
+  # Clone a specific branch (e.g., scarthgap)
+  bit init clone -b scarthgap --execute
+
+  # Clone to a custom layers directory
+  bit init clone --execute --layers-dir my-layers
+""",
+    )
+    init_clone.add_argument(
+        "--execute",
+        action="store_true",
+        help="Actually clone the repos (default: just show commands)",
+    )
+    init_clone.add_argument(
+        "--branch", "-b",
+        default="master",
+        help="Branch to clone (master, scarthgap, kirkstone, etc.)",
+    )
+    init_clone.add_argument(
+        "--layers-dir",
+        default="layers",
+        help="Directory to clone repos into",
+    )
+
+    # Keep bootstrap as an alias for backwards compatibility
+    bootstrap = subparsers.add_parser(
+        "bootstrap",
+        help="(alias for 'init clone') Clone core Yocto/OE repositories",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+NOTE: 'bootstrap' is an alias for 'init clone'. Consider using 'init clone' instead.
+
+Examples:
+  bit init clone --execute
+  bit init clone -b scarthgap --execute
+""",
+    )
+    bootstrap.add_argument(
+        "--clone",
+        action="store_true",
+        help="Actually clone the repos (default: just show commands)",
+    )
+    bootstrap.add_argument(
+        "--branch", "-b",
+        default="master",
+        help="Branch to clone (master, scarthgap, kirkstone, etc.)",
+    )
+    bootstrap.add_argument(
+        "--layers-dir",
+        default="layers",
+        help="Directory to clone repos into",
+    )
+
+    # ---------- search ----------
+    search = subparsers.add_parser(
+        "search",
+        help="Search OpenEmbedded Layer Index for layers",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Browse all layers interactively (fzf)
+  bit search
+
+  # Search for layers matching a term
+  bit search security
+
+  # Clone a layer directly
+  bit search -c meta-virtualization
+
+  # Get layer info for scripting (machine-readable key=value output)
+  bit search -i meta-virtualization
+  # Output: name=..., url=..., depends=..., optional=...
+
+  # Use in scripts:
+  url=$(bit search -i meta-virt | grep '^url=' | cut -d= -f2)
+""",
+    )
+    search.add_argument(
+        "query",
+        nargs="?",
+        help="Search term (searches layer names and descriptions)",
+    )
+    search.add_argument(
+        "--branch", "-b",
+        default="master",
+        help="OE branch to search (master, scarthgap, kirkstone, etc.)",
+    )
+    search.add_argument(
+        "--force", "-f",
+        action="store_true",
+        help="Force refresh from layer index (ignore cache)",
+    )
+    search.add_argument(
+        "--clone", "-c",
+        action="store_true",
+        help="Clone the matching layer (requires exact match or single result)",
+    )
+    search.add_argument(
+        "--target", "-t",
+        metavar="DIR",
+        help="Target directory for clone (default: layers/<name>)",
+    )
+    search.add_argument(
+        "--info", "-i",
+        action="store_true",
+        help="Show layer info (URL, subdir, dependencies) for scripting",
+    )
+
+    # ---------- export ----------
+    export = subparsers.add_parser(
+        "export",
+        help="Export patches from layer repos",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Export all local commits into one directory with aggregate cover letter
+  bit export --target-dir ~/patches
+
+  # Interactively select commits using fzf (or manual input if fzf unavailable)
+  bit export --target-dir ~/patches --pick
+
+  # Export to per-repo subdirectories, each with its own cover letter
+  bit export --target-dir ~/patches --layout per-repo
+
+  # Combine: interactive selection + per-repo subdirectories
+  bit export --target-dir ~/patches --layout per-repo --pick
+
+  # Force overwrite existing export directory
+  bit export --target-dir ~/patches --force
+
+  # Export as version 2 of a patch series
+  bit export --target-dir ~/patches -v 2
+  # Produces: [OE-core][PATCH v2 01/05] commit title
+
+  # Create pull branches in each repo (for git pull requests)
+  bit export --target-dir ~/patches --branch feature-xyz
+  # Creates 'feature-xyz' branch in each repo, cover letter includes pull URLs
+
+Options explained:
+  --layout flat (default):
+      All patches written to --target-dir with one aggregate cover letter.
+
+  --layout per-repo:
+      Each repo gets its own subdirectory with its own cover letter.
+
+  --pick:
+      Interactive commit selection with fzf (Tab to mark, Enter to confirm).
+      Without --pick, exports all commits from origin/<branch>..HEAD.
+
+  -v N, --series-version N:
+      Add version to patch subjects: [PATCH v2 01/05] instead of [PATCH 01/05].
+
+  -b NAME, --branch NAME:
+      Create a pull branch in each repo with the selected commits.
+      Branch is based on origin/<branch> with commits cherry-picked.
+      Cover letter includes 'git pull <url> <branch>' commands.
+      Use --force to overwrite existing branches.
+""",
+    )
+    export.add_argument(
+        "--layout",
+        choices=["flat", "per-repo"],
+        default="flat",
+        help="'flat': all patches in one directory with aggregate cover letter. "
+             "'per-repo': each repo gets its own subdirectory with own cover letter",
+    )
+    export.add_argument(
+        "--target-dir",
+        help="Directory to place exported patches (created if needed)",
+    )
+    export.add_argument(
+        "--force",
+        action="store_true",
+        help="Remove existing contents of target directory before export",
+    )
+    export.add_argument(
+        "--pick",
+        action="store_true",
+        help="Interactively select commits using fzf (or manual input). "
+             "Without this flag, exports all commits from origin/<branch>..HEAD",
+    )
+    export.add_argument(
+        "-v", "--series-version",
+        type=int,
+        metavar="N",
+        help="Version number for patch series (e.g., -v 2 produces [PATCH v2 1/5])",
+    )
+    export.add_argument(
+        "-b", "--branch",
+        metavar="NAME",
+        help="Create a branch with selected commits in each repo for pulling. "
+             "Branch is based on origin/<current-branch> with selected commits cherry-picked. "
+             "Use --force to overwrite existing branches. "
+             "Cover letter will include 'git pull' URLs.",
+    )
+    export.add_argument(
+        "--from-branch",
+        metavar="NAME",
+        help="Export commits from specified branch instead of HEAD. "
+             "Useful after 'export prep --branch' to export from the prep branch.",
+    )
+    export.add_argument(
+        "--export-state-file",
+        default=".bit.export-state.json",
+        help="JSON file to remember previous export choices per repo. "
+             "Stores HEAD SHA, include/skip decision, and range for each repo. "
+             "On next export, if HEAD matches, previous choices become defaults",
+    )
+
+    # Export subcommands
+    export_sub = export.add_subparsers(dest="export_command", metavar="command")
+
+    export_prep = export_sub.add_parser(
+        "prep",
+        help="Group commits for upstream via rebase",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactively select commits to group for upstream in each repo
+  bit export prep
+
+  # Create backup branches before rebasing
+  bit export prep --backup
+
+  # Create a branch for PR submission at the cut point
+  bit export prep --branch zedd/kernel
+
+  # Preview what would happen without making changes
+  bit export prep --dry-run
+
+Workflow:
+  For each repo with local commits:
+  1. Shows commits between origin/<branch> and HEAD
+  2. User selects which commits are destined for upstream (Tab=toggle, Space=range)
+  3. User selects insertion point showing selected commit count
+  4. Reorders: commits before insertion -> upstream commits -> remaining
+  5. Optionally creates a branch at the cut point (via --branch or b/B keys)
+
+  After all repos are processed, prompts to proceed with export.
+  Saves prep state for automatic use by subsequent 'export' command.
+
+This is useful before running 'export' when you have scattered commits
+that need to be grouped together for upstream submission.
+""",
+    )
+    export_prep.add_argument(
+        "--backup",
+        action="store_true",
+        help="Create backup branch (e.g., <branch>-backup-<timestamp>) before rebasing",
+    )
+    export_prep.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would happen without making changes",
+    )
+    export_prep.add_argument(
+        "--plain",
+        action="store_true",
+        help="Use text-based prompts instead of fzf",
+    )
+    export_prep.add_argument(
+        "--branch",
+        metavar="NAME",
+        help="Create branch at last upstream commit for PR submission",
+    )
+
+    # ---------- explore ----------
+    explore = subparsers.add_parser(
+        "explore",
+        aliases=["x"],
+        help="Interactively explore commits in layer repos",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive exploration (fzf)
+  bit explore
+  bit explore OE-core
+
+  # Text status output (like 'status' command)
+  bit explore --status
+  bit explore --status -v
+  bit explore --status --refresh
+
+Repo list navigation:
+  Enter/->  Explore commits in selected repo
+  u        Update (pull --rebase)
+  m        Merge (pull)
+  r        Refresh (fetch from origin)
+  v        Toggle verbose display
+  s        Show detailed status
+  q        Quit
+
+Commit browser navigation:
+  Tab      Toggle single commit selection
+  Space    Mark range endpoints (select all between)
+  ?        Toggle preview pane
+  d        Toggle diff mode (stat vs full patch)
+  c        Copy commit hash to clipboard
+  e        Export selected commit(s) as .patch
+  Esc/b/<- Back to repo list
+  q        Quit entirely
+""",
+    )
+    explore_repo_arg = explore.add_argument(
+        "repo",
+        nargs="?",
+        help="Jump directly to specific repo (by index, name, or path)",
+    )
+    explore.add_argument(
+        "--upstream-count",
+        type=int,
+        default=20,
+        help="Number of upstream commits to show for context",
+    )
+    explore.add_argument(
+        "--status",
+        action="store_true",
+        help="Print text status summary instead of interactive fzf",
+    )
+    explore.add_argument(
+        "--refresh",
+        action="store_true",
+        help="Fetch from origin before showing status",
+    )
+    explore.add_argument(
+        "-v", "--verbose",
+        action="count",
+        default=0,
+        help="Increase verbosity: -v shows commits (limited), -vv shows all commits",
+    )
+    explore.add_argument(
+        "--max-commits",
+        type=int,
+        default=10,
+        help="Max commits to show with -v",
+    )
+    if HAS_ARGCOMPLETE:
+        explore_repo_arg.completer = RepoCompleter()
+
+    # ---------- config ----------
+    config = subparsers.add_parser(
+        "config",
+        aliases=["c"],
+        help="View and configure repo/layer settings",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive config (fzf interface)
+  bit config
+
+  # CLI: View config for a specific repo
+  bit config 1
+  bit config OE-core
+
+  # CLI: Set display name
+  bit config 1 --display-name "OE-core"
+  bit config 1 --display-name ""  # clear
+
+  # CLI: Set update default
+  bit config 1 --update-default skip
+
+  # CLI: Edit layer.conf
+  bit config edit meta-mylayer
+
+Interactive keybindings:
+  Enter/->  Configure repo (submenu with all options)
+  d        Set display name (prompts for input)
+  r        Set default to rebase
+  m        Set default to merge
+  s        Set default to skip
+  e        Edit layer.conf in $EDITOR
+  q        Quit
+""",
+    )
+    config_repo_arg = config.add_argument(
+        "repo",
+        nargs="?",
+        help="Repo index (from list), name, or path to configure. Omit to list all repos. Use 'edit <layer>' to edit layer.conf.",
+    )
+    config_extra_arg = config.add_argument(
+        "extra_arg",
+        nargs="?",
+        help=argparse.SUPPRESS,  # Hidden - used for 'edit <layer>' syntax
+    )
+    if HAS_ARGCOMPLETE:
+        config_repo_arg.completer = RepoCompleter(include_edit=True)
+        config_extra_arg.completer = LayerCompleter()  # For 'edit <layer>'
+    config.add_argument(
+        "--display-name",
+        metavar="NAME",
+        help="Set custom display name for patch subjects (empty string to clear)",
+    )
+    config.add_argument(
+        "--update-default",
+        metavar="ACTION",
+        choices=["rebase", "merge", "skip"],
+        help="Set update default action for the repo (rebase, merge, or skip)",
+    )
+    config.add_argument(
+        "-e", "--edit",
+        action="store_true",
+        help="Open interactive config menu for the specified repo",
+    )
+
+    # ---------- deps ----------
+    deps = subparsers.add_parser(
+        "deps",
+        aliases=["d"],
+        help="Show layer and recipe dependencies",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive layer dependency browser
+  bit deps
+  bit deps layers
+
+  # Show dependency tree for a specific layer
+  bit deps layers meta-oe
+  bit deps layers meta-networking
+
+  # Show reverse dependencies (what depends on this layer)
+  bit deps layers --reverse meta-oe
+  bit deps layers -r core
+
+  # Output formats
+  bit deps layers meta-oe --format=tree   # ASCII tree (default)
+  bit deps layers meta-oe --format=dot    # DOT graph (for graphviz)
+  bit deps layers meta-oe --format=list   # Simple list
+
+  # Text list mode (no fzf)
+  bit deps layers --list
+  bit deps layers --list -v
+
+Key bindings (in fzf browser):
+  Enter    Show dependency tree
+  ctrl-r   Show reverse dependencies
+  ctrl-d   Output DOT format
+  ctrl-a   Full graph DOT output
+  ?        Toggle preview
+  q        Quit
+""",
+    )
+    deps.add_argument(
+        "--list", "-l",
+        action="store_true",
+        help="List all layers (text output, no fzf)",
+    )
+    deps.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Verbose output (with --list)",
+    )
+
+    deps_sub = deps.add_subparsers(dest="deps_command", metavar="command")
+
+    # deps layers
+    deps_layers = deps_sub.add_parser("layers", help="Show layer dependency tree")
+    deps_layers.add_argument(
+        "layer",
+        nargs="?",
+        help="Specific layer name (optional, for tree view)",
+    )
+    deps_layers.add_argument(
+        "-r", "--reverse",
+        action="store_true",
+        help="Show reverse dependencies (what depends on this layer)",
+    )
+    deps_layers.add_argument(
+        "--format",
+        choices=["tree", "dot", "list"],
+        default="tree",
+        help="Output format (default: tree)",
+    )
+    deps_layers.add_argument(
+        "--list", "-l",
+        action="store_true",
+        help="List all layers (text output, no fzf)",
+    )
+    deps_layers.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Verbose output (with --list)",
+    )
+
+    # deps recipe (placeholder for future)
+    deps_recipe = deps_sub.add_parser("recipe", help="Show recipe dependency tree")
+    deps_recipe.add_argument(
+        "recipe",
+        help="Recipe name",
+    )
+    deps_recipe.add_argument(
+        "-r", "--rdepends",
+        action="store_true",
+        help="Include runtime dependencies (RDEPENDS)",
+    )
+    deps_recipe.add_argument(
+        "--format",
+        choices=["tree", "dot", "list"],
+        default="tree",
+        help="Output format (default: tree)",
+    )
+
+    # ---------- branch ----------
+    branch = subparsers.add_parser(
+        "branch",
+        aliases=["b"],
+        help="View and switch branches across repos",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive branch management (fzf interface)
+  bit branch
+
+  # CLI: View current branch for a repo
+  bit branch 1
+  bit branch OE-core
+
+  # CLI: Switch a single repo to a branch
+  bit branch 1 kirkstone
+  bit branch OE-core kirkstone
+
+  # CLI: Switch all repos to the same branch
+  bit branch --all kirkstone
+
+Interactive keybindings:
+  Enter/->  Select repo and pick branch
+  <-        Back to repo list
+  q        Quit
+
+Only clean repos can be switched. Dirty repos are skipped with a warning.
+""",
+    )
+    branch_repo_arg = branch.add_argument(
+        "repo",
+        nargs="?",
+        help="Repo index (from list) or path. Omit to list all repos.",
+    )
+    branch.add_argument(
+        "target_branch",
+        nargs="?",
+        metavar="BRANCH",
+        help="Branch to checkout",
+    )
+    branch.add_argument(
+        "--all",
+        dest="all_repos",
+        action="store_true",
+        help="Switch all repos to the specified branch",
+    )
+    if HAS_ARGCOMPLETE:
+        branch_repo_arg.completer = RepoCompleter()
+
+    # ---------- help ----------
+    help_cmd = subparsers.add_parser(
+        "help",
+        aliases=["h"],
+        help="Browse help for all commands (interactive)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="""\
+Interactive help browser with preview pane.
+
+Browse all commands with live preview of their help text.
+Select a command and press Enter to run it.
+
+Keybindings:
+  Enter    Run selected command
+  \\        Expand/collapse subcommands
+  ?        Toggle preview pane
+  q        Quit
+""",
+    )
+
+    # ---------- projects ----------
+    projects = subparsers.add_parser(
+        "projects",
+        aliases=["p"],
+        help="Manage multiple bit working directories",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="""\
+Manage and switch between multiple Yocto/OE project directories.
+
+Run without subcommands for an interactive project picker.
+
+Projects are stored in ~/.config/bit/projects.json.
+""",
+    )
+    projects_sub = projects.add_subparsers(dest="projects_command", metavar="command")
+
+    # projects add
+    projects_add = projects_sub.add_parser(
+        "add",
+        help="Add a project directory",
+    )
+    projects_add.add_argument(
+        "path",
+        nargs="?",
+        help="Path to project directory (default: current directory)",
+    )
+    projects_add.add_argument(
+        "-n", "--name",
+        help="Display name for the project",
+    )
+    projects_add.add_argument(
+        "-d", "--description",
+        help="Optional description",
+    )
+
+    # projects remove
+    projects_remove = projects_sub.add_parser(
+        "remove",
+        help="Remove a project from the list",
+    )
+    projects_remove.add_argument(
+        "path",
+        nargs="?",
+        help="Path to project directory (interactive if omitted)",
+    )
+
+    # projects list
+    projects_sub.add_parser(
+        "list",
+        help="List all registered projects",
+    )
+
+    # projects shell (alias for init shell)
+    projects_shell = projects_sub.add_parser(
+        "shell",
+        help="Start a shell with build environment (alias for 'init shell')",
+    )
+    projects_shell.add_argument(
+        "--layers-dir",
+        default="layers",
+        help="Directory containing layers (relative to current dir)",
+    )
+
+    # ---------- recipes ----------
+    recipes = subparsers.add_parser(
+        "recipes",
+        aliases=["r"],
+        help="Search and browse BitBake recipes",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Source selection menu, then search/browser
+  bit recipes
+
+  # Browse ALL local recipes (full list, navigate with fzf search)
+  bit recipes --browse
+
+  # Search with a query
+  bit recipes linux
+
+  # Skip menu, search configured layers only
+  bit recipes --configured linux
+
+  # Skip menu, search all local (configured + discovered)
+  bit recipes --local linux
+
+  # Skip menu, search layer index API
+  bit recipes --index linux
+
+  # Filter to specific layer
+  bit recipes --layer meta-oe
+
+  # Filter by SECTION
+  bit recipes --section kernel
+
+  # Text output (no fzf)
+  bit recipes --list linux
+
+  # Rebuild cache
+  bit recipes --force
+
+Key bindings (in fzf browser):
+  Enter   View recipe in $PAGER or $EDITOR
+  ctrl-e  Edit recipe in $EDITOR (local only)
+  alt-c   Copy path to clipboard
+  alt-d   Show recipe dependencies
+  alt-s   Switch source (Configured → Local → Index)
+  ?       Toggle preview
+  q       Quit
+""",
+    )
+    recipes.add_argument(
+        "query",
+        nargs="?",
+        help="Search term (searches recipe names, summaries, descriptions)",
+    )
+    recipes.add_argument(
+        "--browse",
+        action="store_true",
+        help="Browse ALL local recipes (no query filter, full list)",
+    )
+    recipes.add_argument(
+        "--configured",
+        action="store_true",
+        help="Skip menu, search configured layers only",
+    )
+    recipes.add_argument(
+        "--local",
+        action="store_true",
+        help="Skip menu, search all local (configured + discovered)",
+    )
+    recipes.add_argument(
+        "--index",
+        action="store_true",
+        help="Skip menu, search layer index API",
+    )
+    recipes.add_argument(
+        "--layer",
+        metavar="NAME",
+        help="Filter to specific layer",
+    )
+    recipes.add_argument(
+        "--section",
+        metavar="SEC",
+        help="Filter by SECTION (base, kernel, multimedia, etc.)",
+    )
+    recipes.add_argument(
+        "--list",
+        action="store_true",
+        help="Text output (no fzf)",
+    )
+    recipes.add_argument(
+        "--force",
+        action="store_true",
+        help="Rebuild cache",
+    )
+    recipes.add_argument(
+        "--branch", "-b",
+        default="master",
+        help="Branch for layer index API (master, scarthgap, kirkstone, etc.)",
+    )
+    # Search field options
+    recipes.add_argument(
+        "--name", "-n",
+        action="store_true",
+        help="Search recipe names (default if no field specified)",
+    )
+    recipes.add_argument(
+        "--summary", "-s",
+        action="store_true",
+        help="Search SUMMARY field",
+    )
+    recipes.add_argument(
+        "--description", "-d",
+        action="store_true",
+        help="Search DESCRIPTION field",
+    )
+    recipes.add_argument(
+        "--sort",
+        choices=["name", "layer"],
+        default=None,
+        help="Sort results by name (default) or layer",
+    )
+
+    # ---------- fragments ----------
+    fragments = subparsers.add_parser(
+        "fragments",
+        aliases=["f", "frags"],
+        help="Browse and manage OE configuration fragments",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive fragment browser with fzf
+  bit fragments
+
+  # List all available fragments
+  bit fragments list
+  bit fragments list -v
+
+  # Enable a fragment
+  bit fragments enable meta/yocto/sstate-mirror-cdn
+  bit fragments enable machine/qemuarm64
+
+  # Disable a fragment
+  bit fragments disable meta/yocto/sstate-mirror-cdn
+
+  # Show fragment content
+  bit fragments show meta/yocto/sstate-mirror-cdn
+
+Key bindings (in fzf browser):
+  Enter   Toggle enable/disable
+  Tab     Multi-select fragments
+  e       Enable all selected
+  d       Disable all selected
+  v       View fragment file
+  c       Edit toolcfg.conf
+  ?       Toggle preview
+  q       Quit
+""",
+    )
+    fragments.add_argument(
+        "--confpath",
+        default=None,
+        help="Path to toolcfg.conf (default: conf/toolcfg.conf)",
+    )
+    fragments.add_argument(
+        "--list", "-l",
+        action="store_true",
+        help="List all fragments (text output, no fzf)",
+    )
+
+    fragments_sub = fragments.add_subparsers(dest="fragment_command", metavar="command")
+
+    # fragments list
+    fragments_list = fragments_sub.add_parser("list", help="List all available fragments")
+    fragments_list.add_argument("-v", "--verbose", action="store_true", help="Show descriptions")
+
+    # fragments enable
+    fragments_enable = fragments_sub.add_parser("enable", help="Enable a fragment")
+    fragments_enable.add_argument("fragmentname", nargs="+", help="Fragment name(s) to enable")
+
+    # fragments disable
+    fragments_disable = fragments_sub.add_parser("disable", help="Disable a fragment")
+    fragments_disable.add_argument("fragmentname", nargs="+", help="Fragment name(s) to disable")
+
+    # fragments show
+    fragments_show = fragments_sub.add_parser("show", help="Show fragment content")
+    fragments_show.add_argument("fragmentname", help="Fragment name to show")
+
+    return parser, {"export": export}
+
+
+def _has_valid_project_context() -> bool:
+    """
+    Check if we're in a valid bitbake project directory.
+    Returns True if bblayers.conf exists or layers can be discovered.
+    """
+    # Check for bblayers.conf
+    candidates = ["conf/bblayers.conf", "build/conf/bblayers.conf"]
+    for cand in candidates:
+        if os.path.exists(cand):
+            return True
+
+    # Try to discover layers (look for conf/layer.conf files)
+    try:
+        for root, dirs, files in os.walk(".", topdown=True):
+            # Skip hidden dirs and common non-layer dirs
+            dirs[:] = [d for d in dirs if not d.startswith(".") and d not in ("build", "downloads", "sstate-cache", "tmp")]
+            if "conf" in dirs:
+                layer_conf = os.path.join(root, "conf", "layer.conf")
+                if os.path.exists(layer_conf):
+                    return True
+            # Don't go too deep
+            if root.count(os.sep) > 3:
+                dirs.clear()
+    except (OSError, PermissionError):
+        pass
+
+    return False
+
+
+SORT_MODES = ["category", "alpha", "interactive"]
+SORT_MODE_LABELS = {
+    "category": "Category",
+    "alpha": "A-Z",
+    "interactive": "Interactive",
+}
+
+
+def set_menu_sort_mode(mode: str, defaults_file: str = ".bit.defaults") -> bool:
+    """
+    Save menu sort mode to defaults file.
+
+    Args:
+        mode: Sort mode ("category", "alpha", or "interactive")
+        defaults_file: Path to defaults file
+
+    Returns:
+        True if saved successfully
+    """
+    if mode not in SORT_MODES:
+        return False
+
+    try:
+        data = {}
+        if os.path.exists(defaults_file):
+            with open(defaults_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+        data["menu_sort"] = mode
+
+        with open(defaults_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        return True
+    except (json.JSONDecodeError, OSError):
+        return False
+
+
+def fzf_command_menu(defaults_file: str = ".bit.defaults") -> Optional[str]:
+    """Show fzf menu to select a subcommand. Returns command name or None if cancelled."""
+    # Get sort mode from defaults
+    sort_mode = get_menu_sort_mode(defaults_file)
+    current_selection: Optional[str] = None
+
+    while True:
+        # Sort/group commands according to mode
+        sorted_commands, categories = sort_commands_by_mode(COMMAND_TREE, sort_mode)
+
+        # Build header with current sort mode indicator
+        mode_label = SORT_MODE_LABELS.get(sort_mode, sort_mode)
+        header = f"Enter=run | \\=expand | ctrl-s=sort ({mode_label}) | q=quit"
+
+        result = fzf_expandable_menu(
+            sorted_commands,
+            header=header,
+            prompt="bit ",
+            height="~80%",
+            categories=categories,
+            sort_key="ctrl-s",
+            initial_selection=current_selection,
+        )
+
+        # Handle sort mode cycling
+        if isinstance(result, tuple) and result[0] == "SORT":
+            # Preserve cursor position if we have a valid command
+            if result[1]:
+                current_selection = result[1]
+            # Cycle to next sort mode
+            current_idx = SORT_MODES.index(sort_mode) if sort_mode in SORT_MODES else 0
+            sort_mode = SORT_MODES[(current_idx + 1) % len(SORT_MODES)]
+            # Save the new mode
+            set_menu_sort_mode(sort_mode, defaults_file)
+            continue
+
+        # Regular selection or cancel
+        return result
+
+
+def fzf_help_browser() -> Optional[str]:
+    """
+    Interactive help browser with preview pane.
+    Returns command name to run, or None to exit.
+    """
+    # Get the script path for preview commands
+    script_path = os.path.abspath(sys.argv[0])
+
+    # Add (general) to the command tree for help browser
+    commands = [("(general)", "Overview and global options", [])] + COMMAND_TREE
+
+    # Build preview command dynamically from COMMAND_TREE
+    # Collect all subcommands that need special handling (have spaces)
+    subcommand_cases = []
+    subcommand_to_parent = {}
+    for cmd, _, subs in COMMAND_TREE:
+        for subcmd, _ in subs:
+            # Subcommands like "init clone" need explicit elif
+            subcommand_cases.append(
+                f'elif [ "$cmd" = "{subcmd}" ]; then "{script_path}" {subcmd} --help 2>&1; '
+            )
+            # Map subcommand to parent for return value
+            subcommand_to_parent[subcmd] = cmd
+
+    preview_cmd = (
+        f'cmd={{1}}; '
+        f'if [ "$cmd" = "(general)" ]; then "{script_path}" --help 2>&1; '
+        + "".join(subcommand_cases)
+        + f'else "{script_path}" "$cmd" --help 2>&1; fi'
+    )
+
+    # Options provider: parse --help output for command options
+    def get_options(cmd: str) -> List[Tuple[str, str]]:
+        if cmd == "(general)":
+            return parse_help_options(script_path, "")
+        return parse_help_options(script_path, cmd)
+
+    selected = fzf_expandable_menu(
+        commands,
+        header="Enter=run | \\=expand | v=options | ?=preview | q=quit",
+        prompt="Select command: ",
+        height="100%",
+        preview_cmd=preview_cmd,
+        preview_window="right,60%,wrap",
+        options_provider=get_options,
+    )
+
+    if not selected:
+        return None
+
+    # Don't try to "run" general help
+    if selected == "(general)":
+        return None
+
+    # For subcommands, return the parent command
+    if selected in subcommand_to_parent:
+        return subcommand_to_parent[selected]
+
+    return selected
+
+
+def main(argv=None) -> int:
+    """Main entry point."""
+    def handle_sigint(signum, frame):
+        print("\nInterrupted, exiting.")
+        sys.exit(1)
+
+    signal.signal(signal.SIGINT, handle_sigint)
+
+    parser, subparsers = build_parser()
+    if HAS_ARGCOMPLETE:
+        argcomplete.autocomplete(parser)
+    args = parser.parse_args(argv)
+
+    # Import commands module here to avoid circular imports
+    from . import commands
+
+    if args.completion:
+        print("Bash completion setup for bit")
+        print("=" * 42)
+        print()
+        print("1. Install argcomplete:")
+        print("   pip install argcomplete")
+        print()
+        print("2. Add to your ~/.bashrc:")
+        print('   eval "$(register-python-argcomplete bit)"')
+        print()
+        print("3. Reload your shell:")
+        print("   source ~/.bashrc")
+        print()
+        print("Usage:")
+        print("   bit config m<TAB>  # complete repo names")
+        print("   bit config e<TAB>  # complete to 'edit'")
+        print("   bit -<TAB>         # complete options")
+        print()
+        if HAS_ARGCOMPLETE:
+            print("Status: argcomplete is installed")
+        else:
+            print("Status: argcomplete is NOT installed")
+        return 0
+
+    # Check for current project and change to it if set
+    # (skip for 'projects' command itself to avoid confusion)
+    if args.command not in ("projects", "p"):
+        current_project = commands.get_current_project()
+        if current_project and os.path.isdir(current_project):
+            # Only change if we're not already in the project or a subdirectory
+            cwd = os.path.abspath(os.getcwd())
+            proj = os.path.abspath(current_project)
+            if not cwd.startswith(proj):
+                os.chdir(current_project)
+
+    if not args.command:
+        # Check if we're in a valid project context
+        # If not, offer to select/add a project
+        if not _has_valid_project_context():
+            # No project context - show projects picker
+            print("No bblayers.conf found and no layers discovered.")
+            print("Use 'projects' to select or add a project directory.\n")
+            if fzf_available():
+                result = commands.run_projects(args, from_auto_prompt=True)
+                if result == 2:
+                    # User selected a project and wants to see command menu
+                    # Change to the selected project directory
+                    current_project = commands.get_current_project()
+                    if current_project and os.path.isdir(current_project):
+                        os.chdir(current_project)
+                    print()  # Blank line before menu
+                    # Fall through to show command menu
+                else:
+                    return result
+            else:
+                print("Run: bit projects add /path/to/project")
+                return 1
+
+        # Show fzf menu if available, otherwise print help
+        if fzf_available():
+            selected = fzf_command_menu()
+            if selected == "help":
+                # Show interactive help browser
+                cmd_to_run = fzf_help_browser()
+                if cmd_to_run:
+                    # Split in case of subcommands like "init clone", "export prep"
+                    return main(cmd_to_run.split())
+                return 0
+            elif selected:
+                # Re-invoke main with the selected command to get proper arg defaults
+                # Split in case of subcommands like "init clone"
+                return main(selected.split())
+            else:
+                return 0  # Cancelled
+        else:
+            print("Note: Install 'fzf' for interactive menus. Showing help instead.\n")
+            parser.print_help()
+            return 0
+
+    if args.command == "export":
+        export_cmd = getattr(args, "export_command", None)
+        if export_cmd == "prep":
+            return commands.run_prepare_export(args)
+        if not args.target_dir:
+            subparsers["export"].print_help()
+            return 1
+        return commands.run_export(args)
+
+    if args.command in ("update", "u"):
+        return commands.run_update(args)
+    if args.command == "status":
+        # status is an alias for explore --status
+        args.status = True
+        args.refresh = getattr(args, 'fetch', False)  # map old --fetch to --refresh
+        args.repo = None
+        args.upstream_count = 20
+        return commands.run_explore(args)
+    if args.command == "repos":
+        return commands.run_repos(args)
+    if args.command == "init":
+        if getattr(args, "init_command", None) == "clone":
+            # Map init clone args to bootstrap args
+            args.clone = getattr(args, "execute", False)
+            return commands.run_bootstrap(args)
+        if getattr(args, "init_command", None) == "shell":
+            return commands.run_init_shell(args)
+        return commands.run_init(args)
+    if args.command == "bootstrap":
+        # Legacy alias - bootstrap uses --clone, init clone uses --execute
+        return commands.run_bootstrap(args)
+    if args.command == "search":
+        return commands.run_search(args)
+    if args.command in ("config", "c"):
+        return commands.run_config(args)
+    if args.command in ("deps", "d"):
+        return commands.run_deps(args)
+    if args.command in ("branch", "b"):
+        return commands.run_branch(args)
+    if args.command in ("explore", "x"):
+        return commands.run_explore(args)
+    if args.command in ("help", "h"):
+        if fzf_available():
+            cmd_to_run = fzf_help_browser()
+            if cmd_to_run:
+                return main(cmd_to_run.split())
+            return 0
+        else:
+            parser.print_help()
+            return 0
+    if args.command in ("projects", "p"):
+        return commands.run_projects(args)
+    if args.command in ("recipes", "r"):
+        return commands.run_recipe(args)
+    if args.command in ("fragments", "f", "frags"):
+        return commands.run_fragment(args)
+
+    parser.error(f"Unknown command: {args.command}")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())