3 files changed, 52 insertions, 0 deletions
diff --git a/firefly_cli/context.py b/firefly_cli/context.py
new file mode 100644
index 0000000..85d309e
--- /dev/null
+++ b/firefly_cli/context.py
@@ -0,0 +1,8 @@
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>  GPL-2.0-only
+from dataclasses import dataclass
+
+@dataclass
+class Context:
+    client: object        # firefly_cli.client.Client
+    resolver: object      # firefly_cli.resolver.Resolver
+    human: bool = False
diff --git a/firefly_cli/registry.py b/firefly_cli/registry.py
new file mode 100644
index 0000000..f983af8
--- /dev/null
+++ b/firefly_cli/registry.py
@@ -0,0 +1,21 @@
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>  GPL-2.0-only
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+@dataclass
+class Command:
+    name: str            # e.g. "tx add"
+    handler: Callable     # fn(args, ctx) -> int
+    help: str = ""
+    args: Optional[Callable] = None   # fn(argparse_subparser) -> None
+
+_COMMANDS = []
+
+def command(name, help="", args=None):
+    def deco(fn):
+        _COMMANDS.append(Command(name=name, handler=fn, help=help, args=args))
+        return fn
+    return deco
+
+def all_commands():
+    return list(_COMMANDS)
diff --git a/tests/unit/test_registry.py b/tests/unit/test_registry.py
new file mode 100644
index 0000000..f30a5df
--- /dev/null
+++ b/tests/unit/test_registry.py
@@ -0,0 +1,23 @@
+import unittest
+from firefly_cli import registry
+
+class TestRegistry(unittest.TestCase):
+    def setUp(self):
+        registry._COMMANDS.clear()
+
+    def test_command_decorator_registers(self):
+        @registry.command("tx add", help="add a tx")
+        def handler(args, ctx):
+            return 0
+        cmds = registry.all_commands()
+        self.assertEqual(len(cmds), 1)
+        self.assertEqual(cmds[0].name, "tx add")
+        self.assertIs(cmds[0].handler, handler)
+
+    def test_add_arguments_callback_stored(self):
+        def args_cb(p):
+            p.add_argument("name")
+        @registry.command("account get", args=args_cb)
+        def handler(args, ctx):
+            return 0
+        self.assertIs(registry.all_commands()[0].args, args_cb)