tui: --open PATH to create/attach a session for an arbitrary binary

- app: when open_path is set, idb_open (idle_ttl=1e9, long timeout) and pin the
  returned session; clean status on failure (e.g. non-writable dir)
- tui.py: --open flag + usage docs (attach vs open)
- verified: --open targets/cat -> new session, 161 funcs loaded

1 files changed, 23 insertions, 4 deletions

diff --git a/idatui/tui.py b/idatui/tui.py
index 3fc7edd..e787fe6 100644
--- a/idatui/tui.py
+++ b/idatui/tui.py
@@ -1,4 +1,18 @@
-"""Launcher:  python -m idatui.tui [--url URL] [--db SESSION] [--no-keepalive]"""
+"""Launcher for the idatui TUI.
+
+  # attach to the single open session on a running server
+  python -m idatui.tui
+
+  # attach to a specific session
+  python -m idatui.tui --db 80d83396
+
+  # open (or reopen) an arbitrary binary, then drive it
+  python -m idatui.tui --open /path/to/binary
+
+The server (supervisor) must already be running (see spawn.sh). --open creates a
+session via idb_open; the binary's directory must be writable (idalib writes a
+.i64 next to it).
+"""
 from __future__ import annotations
 
 import argparse
@@ -10,12 +24,17 @@ from .client import DEFAULT_URL
 
 def main(argv: list[str] | None = None) -> int:
     p = argparse.ArgumentParser(prog="idatui", description="Minimal TUI for IDA over MCP")
-    p.add_argument("--url", default=os.environ.get("IDA_MCP_URL", DEFAULT_URL))
-    p.add_argument("--db", default=os.environ.get("IDA_MCP_DB"))
+    p.add_argument("--url", default=os.environ.get("IDA_MCP_URL", DEFAULT_URL),
+                   help=f"MCP server URL (default {DEFAULT_URL})")
+    p.add_argument("--db", default=os.environ.get("IDA_MCP_DB"),
+                   help="attach to an existing session id")
+    p.add_argument("--open", metavar="PATH",
+                   help="open (or reopen) a binary and drive it (dir must be writable)")
     p.add_argument("--no-keepalive", action="store_true",
                    help="Do not bump idle-TTL / run the keepalive heartbeat")
     args = p.parse_args(argv)
-    IdaTui(url=args.url, db=args.db, keepalive=not args.no_keepalive).run()
+    IdaTui(url=args.url, db=args.db, open_path=args.open,
+           keepalive=not args.no_keepalive).run()
     return 0