diff options
Diffstat (limited to 'firefly_cli')
| -rw-r--r-- | firefly_cli/__init__.py | 2 | ||||
| -rw-r--r-- | firefly_cli/cli.py | 15 | ||||
| -rw-r--r-- | firefly_cli/commands/account.py | 8 | ||||
| -rw-r--r-- | firefly_cli/commands/auth.py | 4 | ||||
| -rw-r--r-- | firefly_cli/commands/category.py | 2 | ||||
| -rw-r--r-- | firefly_cli/commands/tag.py | 2 | ||||
| -rw-r--r-- | firefly_cli/commands/transaction.py | 8 |
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}) |