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>

5 files changed, 12 insertions, 12 deletions

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})