feat: tx list --flat, account create --if-not-exists, --since/--until doc (v0.3.6)v0.3.6

Three smaller ISSUES.md items, one PATCH (two optional flags + a doc fix; no
existing caller or JSON shape changes).

- tx list --flat: emit one top-level object per split (journal id repeated),
  dropping the transactions[] nesting so single-split journals script cleanly.
  JSON-only; --human already explodes splits into a table.
- account create --if-not-exists: resolve the name first; on a clash return the
  existing account with "existed": true (exit 0) instead of surfacing Firefly's
  422, so import scripts are idempotent. Detects via resolver, not by parsing
  the error string.
- SKILL.md documents that --since/--until filter on the transaction date (the
  value date); Firefly journals have a single date field, no separate book date
  (verified against firefly-iii TimeCollection setRange).

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

10 files changed, 166 insertions, 13 deletions

diff --git a/SKILL.md b/SKILL.md
index 4cf40bb..53ebd6f 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -105,7 +105,10 @@ firefly account create Rent --type expense
 ```
 Supports asset, expense, revenue. asset accounts get the default role
 automatically. Unlike categories/tags, accounts are NOT auto-created by
-`tx add`, create them explicitly here first.
+`tx add`, create them explicitly here first. For idempotent import scripts add
+`--if-not-exists`: if an account with that name already exists it returns that
+account's JSON with `"existed": true` (exit 0) instead of erroring on the name
+clash, so a re-run is safe.
 
 **Validate a batch before writing any of it:** when importing many rows in a
 loop, a mid-batch failure (a `--to` account that doesn't exist yet) leaves the
@@ -136,6 +139,19 @@ firefly account balance test01 --at 2026-05-31  # historical: balance as of that
 ```bash
 firefly tx list --account test01 --since 2026-06-01 --until 2026-06-30
 ```
+`--since`/`--until` filter on the transaction date (the date set on the tx),
+inclusive on both ends. Firefly journals have a single date field, so this is
+the value date used for reconciliation; there is no separate book/entry date.
+
+**Flatten output for scripting.** `tx list` nests each journal's splits under
+`transactions[]` even for the single-split common case. Add `--flat` to get one
+top-level object per split (the journal `id` repeated), with the split fields
+(`amount`, `source_name`, `destination_name`, `category_name`, ...) at the top
+level and no `transactions[]` key:
+```bash
+firefly tx list --account test01 --flat
+```
+`--flat` affects JSON only; `--human` already renders one row per split.
 
 **Look up a transaction by id** (ids come from `tx add`/`tx list` output):
 ```bash
diff --git a/completions/firefly.bash b/completions/firefly.bash
index 648fbe0..6901d14 100644
--- a/completions/firefly.bash
+++ b/completions/firefly.bash
@@ -38,12 +38,12 @@ _firefly() {
     case "$group $leaf" in
         "auth set")         leaf_opts="--token --url";;
         "account balance")  leaf_opts="--at";;
-        "account create")   leaf_opts="--currency --opening-balance --type";;
+        "account create")   leaf_opts="--currency --if-not-exists --opening-balance --type";;
         "account list")     leaf_opts="--type";;
         "tx add")           leaf_opts="--category --date --desc --dry-run --from --skip-dupes --tags --to --type";;
         "tx delete")        leaf_opts="--yes";;
         "tx edit")          leaf_opts="--amount --category --date --desc --from --tags --to --type";;
-        "tx list")          leaf_opts="--account --all --limit --since --until";;
+        "tx list")          leaf_opts="--account --all --flat --limit --since --until";;
     esac
 
     # Leaves per group.
diff --git a/firefly_cli/__init__.py b/firefly_cli/__init__.py
index 4b170ef..27e214f 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.3.5"
+__version__ = "0.3.6"
diff --git a/firefly_cli/commands/account.py b/firefly_cli/commands/account.py
index d78f8fc..81c2e1d 100644
--- a/firefly_cli/commands/account.py
+++ b/firefly_cli/commands/account.py
@@ -23,6 +23,8 @@ def _create_args(p):
     p.add_argument("--opening-balance", dest="opening_balance", default=None,
                    help="initial balance (asset accounts); dated today")
     p.add_argument("--currency", default=None, help="currency code, e.g. EUR")
+    p.add_argument("--if-not-exists", dest="if_not_exists", action="store_true",
+                   help="if an account with this name exists, return it (existed:true) instead of erroring")
 
 @registry.command("account create", help="create an asset, expense, or revenue account", args=_create_args)
 def cmd_create(args, ctx):
@@ -30,6 +32,17 @@ def cmd_create(args, ctx):
         raise FireflyError(
             f'Unsupported account type "{args.type}". '
             f'Use one of: {", ".join(_CREATE_TYPES)}.')
+    if getattr(args, "if_not_exists", False):
+        # Resolve by name to detect existence; avoids parsing Firefly's 422
+        # "name already in use" error string. Missing = ResolutionError -> create.
+        from firefly_cli.errors import ResolutionError
+        try:
+            existing = ctx.resolver.account(args.name)
+        except ResolutionError:
+            existing = None
+        if existing is not None:
+            output.emit({**existing, "existed": True}, human=ctx.human)
+            return 0
     body = {"name": args.name, "type": args.type}
     if args.type == "asset":
         body["account_role"] = "defaultAsset"
diff --git a/firefly_cli/commands/transaction.py b/firefly_cli/commands/transaction.py
index df1ffc4..714d2d4 100644
--- a/firefly_cli/commands/transaction.py
+++ b/firefly_cli/commands/transaction.py
@@ -139,6 +139,8 @@ def _list_args(p):
     p.add_argument("--limit", type=int, default=20)
     p.add_argument("--all", action="store_true",
                    help="fetch every page (ignores --limit truncation)")
+    p.add_argument("--flat", action="store_true",
+                   help="one flat object per split; drop the transactions[] nesting (JSON only)")
 
 @registry.command("tx list", help="list recent transactions (newest first)", args=_list_args)
 def cmd_list(args, ctx):
@@ -162,7 +164,7 @@ def cmd_list(args, ctx):
             if page >= (pg.get("total_pages") or 1):
                 break
             page += 1
-        output.emit(rows, human=ctx.human)
+        output.emit(_maybe_flat(rows, args, ctx), human=ctx.human)
         return 0
 
     resp = ctx.client.request("GET", path, params=params)
@@ -171,9 +173,16 @@ def cmd_list(args, ctx):
     if total is not None and count is not None and count < total:
         import sys
         print(f"showing {count} of {total} (use --all for all)", file=sys.stderr)
-    output.emit(output.unwrap(resp), human=ctx.human)
+    output.emit(_maybe_flat(output.unwrap(resp), args, ctx), human=ctx.human)
     return 0
 
+# --flat is a JSON-only convenience; --human already explodes splits into a
+# table, so leave its nested rows alone.
+def _maybe_flat(rows, args, ctx):
+    if getattr(args, "flat", False) and not ctx.human:
+        return output.flatten_tx(rows)
+    return rows
+
 def _id_arg(p):
     p.add_argument("id")
 
diff --git a/firefly_cli/output.py b/firefly_cli/output.py
index 166e1bf..6c6a61c 100644
--- a/firefly_cli/output.py
+++ b/firefly_cli/output.py
@@ -62,6 +62,27 @@ def _tx_rows(rows):
 def _is_tx(rows):
     return bool(rows) and isinstance(rows[0], dict) and "transactions" in rows[0]
 
+def flatten_tx(rows):
+    """Explode unwrapped tx journals into one flat object per split.
+
+    Each journal is {id, transactions: [split, ...], ...}. We emit one object
+    per split: the split's raw Firefly fields (source_name, amount, etc.) with
+    the journal id merged in and the `transactions` list dropped. Single-split
+    journals (the common case) become one clean object. Rows without a
+    `transactions` list pass through unchanged.
+    """
+    out = []
+    for r in rows:
+        splits = r.get("transactions")
+        if not isinstance(splits, list):
+            out.append(r)
+            continue
+        for s in splits:
+            flat = dict(s)
+            flat["id"] = r.get("id")
+            out.append(flat)
+    return out
+
 # Per-resource column whitelists for --human. Firefly returns ~50 fields per
 # row; only a handful are worth a table. A row is matched by a signature key.
 # (signature, columns) -- first match wins; unmatched rows use a generic table.
diff --git a/pyproject.toml b/pyproject.toml
index 7e1dbcd..86e8e62 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "firefly-iii-agent"
-version = "0.3.5"
+version = "0.3.6"
 description = "CLI tool for agent interaction with Firefly III"
 readme = "README.md"
 requires-python = ">=3.11"
diff --git a/tests/unit/test_commands_account.py b/tests/unit/test_commands_account.py
index 4a01292..c328890 100644
--- a/tests/unit/test_commands_account.py
+++ b/tests/unit/test_commands_account.py
@@ -43,7 +43,8 @@ class TestAccountCmd(unittest.TestCase):
 
 class TestAccountCreate(unittest.TestCase):
     def _args(self, **kw):
-        base = dict(name=None, type=None, opening_balance=None, currency=None)
+        base = dict(name=None, type=None, opening_balance=None, currency=None,
+                    if_not_exists=False)
         base.update(kw)
         m = MagicMock()
         m.configure_mock(**base)  # 'name' is reserved in MagicMock ctor, not configure_mock
@@ -89,3 +90,36 @@ class TestAccountCreate(unittest.TestCase):
         with self.assertRaises(FireflyError):
             acct.cmd_create(self._args(name="X", type="bogus"), ctx)
         client.request.assert_not_called()
+
+    def test_if_not_exists_returns_existing_no_post(self):
+        ctx, client, resolver = make_ctx()
+        resolver.account.return_value = {"id": "5", "name": "Savings",
+                                         "type": "asset"}
+        rc = acct.cmd_create(
+            self._args(name="Savings", type="asset", if_not_exists=True), ctx)
+        self.assertEqual(rc, 0)
+        resolver.account.assert_called_once_with("Savings")
+        client.request.assert_not_called()  # existed -> no create
+
+    def test_if_not_exists_creates_when_missing(self):
+        from firefly_cli.errors import ResolutionError
+        ctx, client, resolver = make_ctx()
+        resolver.account.side_effect = ResolutionError('No account named "Savings"')
+        client.request.return_value = {"data": {"id": "9", "attributes": {}}}
+        rc = acct.cmd_create(
+            self._args(name="Savings", type="asset", if_not_exists=True), ctx)
+        self.assertEqual(rc, 0)
+        method, path = client.request.call_args[0][:2]
+        self.assertEqual((method, path), ("POST", "/api/v1/accounts"))
+
+    def test_if_not_exists_emits_existed_flag(self):
+        import io, json
+        from contextlib import redirect_stdout
+        ctx, client, resolver = make_ctx()
+        resolver.account.return_value = {"id": "5", "name": "Savings"}
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            acct.cmd_create(
+                self._args(name="Savings", type="asset", if_not_exists=True), ctx)
+        self.assertEqual(json.loads(buf.getvalue()),
+                         {"id": "5", "name": "Savings", "existed": True})
diff --git a/tests/unit/test_commands_transaction.py b/tests/unit/test_commands_transaction.py
index 0fa02ac..28882d3 100644
--- a/tests/unit/test_commands_transaction.py
+++ b/tests/unit/test_commands_transaction.py
@@ -264,7 +264,7 @@ class TestTxList(unittest.TestCase):
         ctx, client, _ = make_ctx()
         client.request.return_value = {"data": []}
         args = MagicMock(since="2026-06-01", until="2026-06-30",
-                         account=None, limit=10, all=False)
+                         account=None, limit=10, all=False, flat=False)
         tx.cmd_list(args, ctx)
         params = client.request.call_args[1]["params"]
         self.assertEqual(params["start"], "2026-06-01")
@@ -280,7 +280,7 @@ class TestTxList(unittest.TestCase):
             "meta": {"pagination": {"total": 90, "count": 20,
                                     "current_page": 1, "total_pages": 5}},
         }
-        args = MagicMock(since=None, until=None, account=None, limit=20, all=False)
+        args = MagicMock(since=None, until=None, account=None, limit=20, all=False, flat=False)
         buf = io.StringIO()
         with redirect_stderr(buf):
             tx.cmd_list(args, ctx)
@@ -296,12 +296,49 @@ class TestTxList(unittest.TestCase):
             "meta": {"pagination": {"total": 1, "count": 1,
                                     "current_page": 1, "total_pages": 1}},
         }
-        args = MagicMock(since=None, until=None, account=None, limit=20, all=False)
+        args = MagicMock(since=None, until=None, account=None, limit=20, all=False, flat=False)
         buf = io.StringIO()
         with redirect_stderr(buf):
             tx.cmd_list(args, ctx)
         self.assertEqual(buf.getvalue(), "")
 
+    def test_list_flat_explodes_splits_json(self):
+        import io, json
+        from contextlib import redirect_stdout
+        ctx, client, _ = make_ctx()
+        client.request.return_value = {
+            "data": [{"id": "7", "type": "transactions", "attributes": {
+                "transactions": [{"amount": "5", "source_name": "A"}]}}],
+            "meta": {"pagination": {"total": 1, "count": 1, "total_pages": 1}},
+        }
+        args = MagicMock(since=None, until=None, account=None, limit=20,
+                         all=False, flat=True)
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            tx.cmd_list(args, ctx)
+        out = json.loads(buf.getvalue())
+        self.assertEqual(out, [{"amount": "5", "source_name": "A", "id": "7"}])
+
+    def test_list_flat_skipped_for_human(self):
+        # --human path must keep nested rows so the table renderer explodes them.
+        import io
+        from contextlib import redirect_stdout
+        ctx, client, _ = make_ctx()
+        ctx = Context(client=client, resolver=ctx.resolver, human=True)
+        client.request.return_value = {
+            "data": [{"id": "7", "attributes": {
+                "transactions": [{"amount": "5", "source_name": "A",
+                                  "destination_name": "B", "type": "withdrawal"}]}}],
+            "meta": {"pagination": {"total": 1, "count": 1, "total_pages": 1}},
+        }
+        args = MagicMock(since=None, until=None, account=None, limit=20,
+                         all=False, flat=True)
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            tx.cmd_list(args, ctx)
+        # human table shows the exploded split value; not raw JSON
+        self.assertIn("5", buf.getvalue())
+
     def test_list_all_paginates(self):
         ctx, client, _ = make_ctx()
         def page(method, path, params=None, body=None):
@@ -312,7 +349,7 @@ class TestTxList(unittest.TestCase):
                                         "current_page": p, "total_pages": 2}},
             }
         client.request.side_effect = page
-        args = MagicMock(since=None, until=None, account=None, limit=2, all=True)
+        args = MagicMock(since=None, until=None, account=None, limit=2, all=True, flat=False)
         rc = tx.cmd_list(args, ctx)
         self.assertEqual(rc, 0)
         self.assertEqual(client.request.call_count, 2)
diff --git a/tests/unit/test_output.py b/tests/unit/test_output.py
index 2e3e5ea..069a21d 100644
--- a/tests/unit/test_output.py
+++ b/tests/unit/test_output.py
@@ -1,6 +1,6 @@
 import io, json, unittest
 from contextlib import redirect_stdout
-from firefly_cli.output import unwrap, emit
+from firefly_cli.output import unwrap, emit, flatten_tx
 
 class TestOutput(unittest.TestCase):
     def test_unwrap_list_returns_clean_objects(self):
@@ -22,6 +22,29 @@ class TestOutput(unittest.TestCase):
             emit([{"id": "1", "name": "x"}], human=False)
         self.assertEqual(json.loads(buf.getvalue()), [{"id": "1", "name": "x"}])
 
+    def test_flatten_single_split(self):
+        rows = [{"id": "10", "group_title": None, "transactions": [
+            {"amount": "5.00", "source_name": "A", "destination_name": "B",
+             "type": "withdrawal"}]}]
+        flat = flatten_tx(rows)
+        self.assertEqual(len(flat), 1)
+        self.assertNotIn("transactions", flat[0])
+        self.assertEqual(flat[0]["id"], "10")
+        self.assertEqual(flat[0]["amount"], "5.00")
+        self.assertEqual(flat[0]["source_name"], "A")
+
+    def test_flatten_multi_split_repeats_id(self):
+        rows = [{"id": "20", "transactions": [
+            {"amount": "1", "type": "withdrawal"},
+            {"amount": "2", "type": "withdrawal"}]}]
+        flat = flatten_tx(rows)
+        self.assertEqual([f["id"] for f in flat], ["20", "20"])
+        self.assertEqual([f["amount"] for f in flat], ["1", "2"])
+
+    def test_flatten_passes_through_non_tx_rows(self):
+        rows = [{"id": "1", "name": "Checking"}]
+        self.assertEqual(flatten_tx(rows), rows)
+
     def test_emit_human_table_contains_values(self):
         buf = io.StringIO()
         with redirect_stdout(buf):