UX: CLI should show errors for unknown commands and contextual help for subcommands

[ianmuscat]

The CLI has two related UX issues with command parsing and help:

1. Unknown/invalid commands silently launch the TUI instead of showing an error
2. Requesting help for a subcommand shows top-level help instead of contextual help

Issue 1: Unknown commands silently launch TUI

Reproduction

btca nonexistent-command

Expected: An error message like error: unknown command 'nonexistent-command'

Actual: The TUI launches silently with no indication that the command was invalid.

Another example (typo)

btca remoev my-resource

Expected: An error like error: unknown command 'remoev'. Did you mean 'remove'?

Actual: The TUI launches, and the user has no idea their command was ignored.

Root Cause

The CLI has a default action handler that catches all unmatched input and launches the TUI:

https://github.com/davis7dotsh/better-context/blob/main/apps/cli/src/index.ts#L55-L81

This design means any typo, unknown command, or invalid subcommand silently falls through to the TUI (which to me was confusing)

Issue 2: No contextual help for subcommands

Reproduction

btca add --help

Expected: Detailed help for the add subcommand, including its options and usage.

Actual: Shows top-level btca --help output:

Usage: btca [options] [command]

CLI for asking questions about technologies using btca server

Options:
  -v, --version                output the version number
  --server <url>               Use an existing btca server URL
  --port <port>                Port for auto-started server (default: random)
  --no-tui                     Use simple REPL mode instead of TUI
  -h, --help                   display help for command

Commands:
  add [options] [url-or-path]  Add a resource (git repository or local directory)
  remove [options] [name]      Remove a resource from the configuration
  ...

This doesn't show the specific options for add like --name, --branch, --search-path, etc.

Expected behavior

Running btca add --help should show something like:

Usage: btca add [options] [url-or-path]

Add a resource (git repository or local directory)

Arguments:
  url-or-path              Git URL or local path to add

Options:
  -n, --name <name>        Resource name (derived from URL/path if not specified)
  -b, --branch <branch>    Git branch (default: "main")
  --search-path <path...>  Subdirectory to focus on (repeatable)
  --notes <notes>          Special notes for the AI
  -h, --help               display help for command

Suggested improvements

1. Error on unknown commands, or handle it in the default action by checking if arguments were passed.
2. Enable contextual subcommand help

Impact

These issues make the CLI a tad frustrating to use.

• Users can't discover why their commands aren't working
• Users can't learn command options without reading source code or external docs
• Typos are silently ignored, leading to confusion
• The behavior differs from standard CLI conventions (e.g., git, npm, docker... all show errors for unknown commands)

Environment

• btca version: latest from npm
• Affects: all platforms