help, completion: descriptive help text and bash completionv0.2.1

Add group/leaf descriptions to argparse help and richer command help
strings. Add generated bash completion (completions/firefly.bash) plus
its generator (scripts/gen_completion.py), wired into the command
checklist in CLAUDE.md and documented in the README. Bump to 0.2.1.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

7 files changed, 26 insertions, 15 deletions

diff --git a/firefly_cli/__init__.py b/firefly_cli/__init__.py
index f50a029..e025931 100644
--- a/firefly_cli/__init__.py
+++ b/firefly_cli/__init__.py
@@ -2,4 +2,4 @@
 # Copyright (C) 2026 Danilo M. <danix@danix.xyz>
 # Licensed under the GNU General Public License v2.0 only.
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
diff --git a/firefly_cli/cli.py b/firefly_cli/cli.py
index d547455..ad54504 100644
--- a/firefly_cli/cli.py
+++ b/firefly_cli/cli.py
@@ -11,6 +11,16 @@ import firefly_cli.commands  # noqa: F401  triggers registration
 # Commands that must work without a configured client.
 _NO_CLIENT = {"auth set"}
 
+# Short blurb per command group, shown in `firefly --help` and as the
+# description in `firefly <group> --help`.
+_GROUP_HELP = {
+    "auth": "configure and verify the Firefly III connection (url + token)",
+    "account": "list, create, and inspect accounts (asset, expense, revenue)",
+    "category": "list categories (categories auto-create when used on a tx)",
+    "tag": "list tags (tags auto-create when attached to a tx)",
+    "tx": "record, list, and search transactions",
+}
+
 def _build_parser():
     parser = argparse.ArgumentParser(prog="firefly",
         description="CLI for Firefly III")
@@ -25,9 +35,10 @@ def _build_parser():
     for cmd in registry.all_commands():
         group, _, leaf = cmd.name.partition(" ")
         if group not in groups:
-            gp = sub.add_parser(group)
+            blurb = _GROUP_HELP.get(group)
+            gp = sub.add_parser(group, help=blurb, description=blurb)
             groups[group] = gp.add_subparsers(dest="_leaf", required=True)
-        lp = groups[group].add_parser(leaf, help=cmd.help)
+        lp = groups[group].add_parser(leaf, help=cmd.help, description=cmd.help)
         if cmd.args:
             cmd.args(lp)
         lp.set_defaults(_handler=cmd.handler, _cmdname=cmd.name)
diff --git a/firefly_cli/commands/account.py b/firefly_cli/commands/account.py
index 0e86b2b..9dbfab6 100644
--- a/firefly_cli/commands/account.py
+++ b/firefly_cli/commands/account.py
@@ -9,7 +9,7 @@ _CREATE_TYPES = ("asset", "expense", "revenue")
 def _list_args(p):
     p.add_argument("--type", help="filter: asset, expense, revenue, liability, ...")
 
-@registry.command("account list", help="list accounts", args=_list_args)
+@registry.command("account list", help="list accounts; optionally filter by --type", args=_list_args)
 def cmd_list(args, ctx):
     params = {"type": args.type} if getattr(args, "type", None) else None
     resp = ctx.client.request("GET", "/api/v1/accounts", params=params)
@@ -24,7 +24,7 @@ def _create_args(p):
                    help="initial balance (asset accounts); dated today")
     p.add_argument("--currency", default=None, help="currency code, e.g. EUR")
 
-@registry.command("account create", help="create an account", args=_create_args)
+@registry.command("account create", help="create an asset, expense, or revenue account", args=_create_args)
 def cmd_create(args, ctx):
     if args.type not in _CREATE_TYPES:
         raise FireflyError(
@@ -46,13 +46,13 @@ def cmd_create(args, ctx):
 def _name_arg(p):
     p.add_argument("account", help="account name or id")
 
-@registry.command("account get", help="show one account", args=_name_arg)
+@registry.command("account get", help="show full details for one account (name or id)", args=_name_arg)
 def cmd_get(args, ctx):
     acc = ctx.resolver.account(args.account)
     output.emit(acc, human=ctx.human)
     return 0
 
-@registry.command("account balance", help="show account balance", args=_name_arg)
+@registry.command("account balance", help="show current balance for one account (name or id)", args=_name_arg)
 def cmd_balance(args, ctx):
     acc = ctx.resolver.account(args.account)
     output.emit({"id": acc["id"], "name": acc.get("name"),
diff --git a/firefly_cli/commands/auth.py b/firefly_cli/commands/auth.py
index d2319e9..99e79c9 100644
--- a/firefly_cli/commands/auth.py
+++ b/firefly_cli/commands/auth.py
@@ -6,7 +6,7 @@ def _set_args(p):
     p.add_argument("--url", help="Firefly III base URL")
     p.add_argument("--token", help="Personal Access Token")
 
-@registry.command("auth set", help="write url+token to config", args=_set_args)
+@registry.command("auth set", help="save url + token to the config file (no API call)", args=_set_args)
 def cmd_set(args, ctx):
     url = args.url or input("Firefly III URL: ").strip()
     token = args.token or getpass.getpass("Personal Access Token: ").strip()
@@ -14,7 +14,7 @@ def cmd_set(args, ctx):
     output.emit({"written": str(path)}, human=ctx.human)
     return 0
 
-@registry.command("auth test", help="verify connectivity and token")
+@registry.command("auth test", help="check the configured url + token reach Firefly")
 def cmd_test(args, ctx):
     resp = ctx.client.request("GET", "/api/v1/about")
     output.emit(resp.get("data", resp), human=ctx.human)
diff --git a/firefly_cli/commands/category.py b/firefly_cli/commands/category.py
index a7ddbe8..d4bad93 100644
--- a/firefly_cli/commands/category.py
+++ b/firefly_cli/commands/category.py
@@ -1,7 +1,7 @@
 # Copyright (C) 2026 Danilo M. <danix@danix.xyz>  GPL-2.0-only
 from firefly_cli import registry, output
 
-@registry.command("category list", help="list categories")
+@registry.command("category list", help="list all categories known to Firefly")
 def cmd_list(args, ctx):
     resp = ctx.client.request("GET", "/api/v1/categories")
     output.emit(output.unwrap(resp), human=ctx.human)
diff --git a/firefly_cli/commands/tag.py b/firefly_cli/commands/tag.py
index 668c4ae..beed56c 100644
--- a/firefly_cli/commands/tag.py
+++ b/firefly_cli/commands/tag.py
@@ -1,7 +1,7 @@
 # Copyright (C) 2026 Danilo M. <danix@danix.xyz>  GPL-2.0-only
 from firefly_cli import registry, output
 
-@registry.command("tag list", help="list tags")
+@registry.command("tag list", help="list all tags known to Firefly")
 def cmd_list(args, ctx):
     resp = ctx.client.request("GET", "/api/v1/tags")
     output.emit(output.unwrap(resp), human=ctx.human)
diff --git a/firefly_cli/commands/transaction.py b/firefly_cli/commands/transaction.py
index be8d281..67d8b71 100644
--- a/firefly_cli/commands/transaction.py
+++ b/firefly_cli/commands/transaction.py
@@ -30,7 +30,7 @@ def _add_args(p):
     p.add_argument("--type", default=None,
                    help="withdrawal|deposit|transfer (overrides inference)")
 
-@registry.command("tx add", help="record a transaction", args=_add_args)
+@registry.command("tx add", help="record a transaction; source/destination resolve to accounts, category/tags auto-create", args=_add_args)
 def cmd_add(args, ctx):
     src = ctx.resolver.account(args.source)
     dst = ctx.resolver.account(args.dest)
@@ -60,7 +60,7 @@ def _list_args(p):
     p.add_argument("--account", default=None, help="filter by account name")
     p.add_argument("--limit", type=int, default=20)
 
-@registry.command("tx list", help="list transactions", args=_list_args)
+@registry.command("tx list", help="list recent transactions (newest first)", args=_list_args)
 def cmd_list(args, ctx):
     if args.account:
         acc = ctx.resolver.account(args.account)
@@ -79,7 +79,7 @@ def cmd_list(args, ctx):
 def _id_arg(p):
     p.add_argument("id")
 
-@registry.command("tx get", help="show one transaction", args=_id_arg)
+@registry.command("tx get", help="show full details for one transaction by id", args=_id_arg)
 def cmd_get(args, ctx):
     resp = ctx.client.request("GET", f"/api/v1/transactions/{args.id}")
     output.emit(output.unwrap(resp), human=ctx.human)
@@ -88,7 +88,7 @@ def cmd_get(args, ctx):
 def _query_arg(p):
     p.add_argument("query")
 
-@registry.command("tx search", help="search transactions", args=_query_arg)
+@registry.command("tx search", help="search transactions by Firefly query string", args=_query_arg)
 def cmd_search(args, ctx):
     resp = ctx.client.request("GET", "/api/v1/search/transactions",
                               params={"query": args.query})