stata-cli 0.2.2__tar.gz → 0.3.0__tar.gz

{stata_cli-0.2.2 → stata_cli-0.3.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: stata-cli
-Version: 0.2.2
+Version: 0.3.0
 Summary: Command-line interface for running Stata commands via PyStata
 License: MIT
 Keywords: stata,cli,statistics,data-science
-Requires-Python: >=3.10
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: click>=8.0
 Provides-Extra: data
@@ -13,8 +13,10 @@ Requires-Dist: pandas; extra == "data"
 
 # stata-cli
 
+![stata-cli banner](assets/banner.png)
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://www.python.org/)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.9-blue.svg)](https://www.python.org/)
 [![npm version](https://img.shields.io/npm/v/stata-cli.svg)](https://www.npmjs.com/package/stata-cli)
 
 [中文版](README.zh.md) | [English](README.md)
@@ -39,10 +41,16 @@ A command-line interface for [Stata](https://www.stata.com/) via PyStata — bui
 | **Run Code** | Execute inline Stata code, multi-line blocks, or pipe from stdin |
 | **Do Files** | Run `.do` files with `///` line continuation support and graph auto-naming |
 | **Data Viewer** | View current dataset as JSON with `if`-condition filtering and row limits |
+| **Variable Metadata** | Inspect variable names, types, formats, and labels via `vars` |
+| **Stored Results** | Retrieve r(), e(), s() results as structured JSON via `return` |
+| **Matrix Access** | Read Stata matrices (e.g. `e(b)`, `e(V)`) as JSON via `matrix` |
+| **Value Labels** | List and inspect value labels via `labels` |
+| **Macro Access** | Get/set Stata macros including `c()`, `e()`, `r()` system macros |
+| **Frame Management** | List Stata frames and current working frame via `frame` |
 | **Help System** | Browse Stata help topics with SMCL-to-plain-text conversion |
-| **Graph Export** | Auto-detect and export graphs as PNG to `~/.stata-cli/graphs/` |
+| **Graph Export** | Auto-detect and export graphs as PNG/SVG/PDF to `~/.stata-cli/graphs/` |
 | **Daemon Mode** | Persistent background process for sub-second execution via Unix socket |
-| **Output Control** | Compact mode, JSON output, token limit management with full-output file save |
+| **Output Control** | Compact mode, JSON output, token limit management, log file output |
 | **Interruption** | Send break signal to stop long-running commands |
 
 ## Installation & Quick Start
@@ -50,7 +58,7 @@ A command-line interface for [Stata](https://www.stata.com/) via PyStata — bui
 ### Requirements
 
 - **Stata 17+** installed on your machine (provides the PyStata library)
-- Python 3.10+
+- Python 3.9+
 
 ### Quick Start (Human Users)
 
@@ -197,6 +205,60 @@ stata-cli detect
 
 Prints the auto-detected Stata installation path.
 
+### `return` — Retrieve Stored Results
+
+```bash
+stata-cli return r         # r() results (after summarize, etc.)
+stata-cli return e         # e() results (after regress, etc.)
+stata-cli return s         # s() results
+```
+
+Returns r(), e(), or s() stored results as structured JSON — scalars, macros, and matrix references.
+
+### `vars` — Variable Metadata
+
+```bash
+stata-cli vars                # all variables
+stata-cli vars price mpg      # specific variables
+```
+
+Returns variable names, types, formats, and labels as JSON. More structured than `describe`.
+
+### `matrix` — Read Stata Matrices
+
+```bash
+stata-cli matrix e(b)         # coefficient vector
+stata-cli matrix e(V)         # variance-covariance matrix
+```
+
+Returns matrix data, dimensions, and row/column names as JSON.
+
+### `labels` — Value Labels
+
+```bash
+stata-cli labels               # list all value label names
+stata-cli labels origin        # show value-label mapping
+stata-cli labels --var foreign # show label attached to a variable
+```
+
+### `macro` — Get/Set Macros
+
+```bash
+stata-cli macro get "c(current_date)"
+stata-cli macro get "e(cmd)"
+stata-cli macro set myvar "hello"
+```
+
+Access Stata macros including system macros (`c()`, `e()`, `r()`).
+
+### `frame` — List Frames
+
+```bash
+stata-cli frame
+```
+
+Shows all Stata frames and the current working frame.
+
 ## Daemon Mode
 
 The daemon keeps PyStata alive in the background — reduces execution time from **~2-3s to ~85ms** (35x speedup).
@@ -234,6 +296,8 @@ The daemon auto-shuts down after 1 hour of inactivity (configurable with `--idle
 | `--max-tokens N` | Max output tokens (0=unlimited) | 0 |
 | `--no-daemon` | Force direct execution | off |
 | `--graphs-dir PATH` | Graph export directory | `~/.stata-cli/graphs/` |
+| `--graph-format [png\|svg\|pdf]` | Graph export format | `png` |
+| `--log PATH` | Save output to a log file | off |
 
 ### JSON Output
 
@@ -313,6 +377,21 @@ regress price mpg weight
 predict yhat
 list make price yhat in 1/5"
 
+# Retrieve regression results as structured JSON
+stata-cli return e
+
+# Get coefficient matrix
+stata-cli matrix e(b)
+
+# Inspect variable metadata
+stata-cli vars price mpg weight
+
+# Check value labels
+stata-cli labels --var foreign
+
+# Read system macros
+stata-cli macro get "c(N)"
+
 # Check data after loading
 stata-cli data --if "price>10000"
 
@@ -325,6 +404,9 @@ describe"
 
 # JSON mode for structured parsing
 stata-cli --json run "display 1+1"
+
+# Export graph as SVG
+stata-cli --graph-format svg run "scatter price mpg"
 ```
 
 ## Contributing

{stata_cli-0.2.2 → stata_cli-0.3.0}/README.md

@@ -1,7 +1,9 @@
 # stata-cli
 
+![stata-cli banner](assets/banner.png)
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://www.python.org/)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.9-blue.svg)](https://www.python.org/)
 [![npm version](https://img.shields.io/npm/v/stata-cli.svg)](https://www.npmjs.com/package/stata-cli)
 
 [中文版](README.zh.md) | [English](README.md)
@@ -26,10 +28,16 @@ A command-line interface for [Stata](https://www.stata.com/) via PyStata — bui
 | **Run Code** | Execute inline Stata code, multi-line blocks, or pipe from stdin |
 | **Do Files** | Run `.do` files with `///` line continuation support and graph auto-naming |
 | **Data Viewer** | View current dataset as JSON with `if`-condition filtering and row limits |
+| **Variable Metadata** | Inspect variable names, types, formats, and labels via `vars` |
+| **Stored Results** | Retrieve r(), e(), s() results as structured JSON via `return` |
+| **Matrix Access** | Read Stata matrices (e.g. `e(b)`, `e(V)`) as JSON via `matrix` |
+| **Value Labels** | List and inspect value labels via `labels` |
+| **Macro Access** | Get/set Stata macros including `c()`, `e()`, `r()` system macros |
+| **Frame Management** | List Stata frames and current working frame via `frame` |
 | **Help System** | Browse Stata help topics with SMCL-to-plain-text conversion |
-| **Graph Export** | Auto-detect and export graphs as PNG to `~/.stata-cli/graphs/` |
+| **Graph Export** | Auto-detect and export graphs as PNG/SVG/PDF to `~/.stata-cli/graphs/` |
 | **Daemon Mode** | Persistent background process for sub-second execution via Unix socket |
-| **Output Control** | Compact mode, JSON output, token limit management with full-output file save |
+| **Output Control** | Compact mode, JSON output, token limit management, log file output |
 | **Interruption** | Send break signal to stop long-running commands |
 
 ## Installation & Quick Start
@@ -37,7 +45,7 @@ A command-line interface for [Stata](https://www.stata.com/) via PyStata — bui
 ### Requirements
 
 - **Stata 17+** installed on your machine (provides the PyStata library)
-- Python 3.10+
+- Python 3.9+
 
 ### Quick Start (Human Users)
 
@@ -184,6 +192,60 @@ stata-cli detect
 
 Prints the auto-detected Stata installation path.
 
+### `return` — Retrieve Stored Results
+
+```bash
+stata-cli return r         # r() results (after summarize, etc.)
+stata-cli return e         # e() results (after regress, etc.)
+stata-cli return s         # s() results
+```
+
+Returns r(), e(), or s() stored results as structured JSON — scalars, macros, and matrix references.
+
+### `vars` — Variable Metadata
+
+```bash
+stata-cli vars                # all variables
+stata-cli vars price mpg      # specific variables
+```
+
+Returns variable names, types, formats, and labels as JSON. More structured than `describe`.
+
+### `matrix` — Read Stata Matrices
+
+```bash
+stata-cli matrix e(b)         # coefficient vector
+stata-cli matrix e(V)         # variance-covariance matrix
+```
+
+Returns matrix data, dimensions, and row/column names as JSON.
+
+### `labels` — Value Labels
+
+```bash
+stata-cli labels               # list all value label names
+stata-cli labels origin        # show value-label mapping
+stata-cli labels --var foreign # show label attached to a variable
+```
+
+### `macro` — Get/Set Macros
+
+```bash
+stata-cli macro get "c(current_date)"
+stata-cli macro get "e(cmd)"
+stata-cli macro set myvar "hello"
+```
+
+Access Stata macros including system macros (`c()`, `e()`, `r()`).
+
+### `frame` — List Frames
+
+```bash
+stata-cli frame
+```
+
+Shows all Stata frames and the current working frame.
+
 ## Daemon Mode
 
 The daemon keeps PyStata alive in the background — reduces execution time from **~2-3s to ~85ms** (35x speedup).
@@ -221,6 +283,8 @@ The daemon auto-shuts down after 1 hour of inactivity (configurable with `--idle
 | `--max-tokens N` | Max output tokens (0=unlimited) | 0 |
 | `--no-daemon` | Force direct execution | off |
 | `--graphs-dir PATH` | Graph export directory | `~/.stata-cli/graphs/` |
+| `--graph-format [png\|svg\|pdf]` | Graph export format | `png` |
+| `--log PATH` | Save output to a log file | off |
 
 ### JSON Output
 
@@ -300,6 +364,21 @@ regress price mpg weight
 predict yhat
 list make price yhat in 1/5"
 
+# Retrieve regression results as structured JSON
+stata-cli return e
+
+# Get coefficient matrix
+stata-cli matrix e(b)
+
+# Inspect variable metadata
+stata-cli vars price mpg weight
+
+# Check value labels
+stata-cli labels --var foreign
+
+# Read system macros
+stata-cli macro get "c(N)"
+
 # Check data after loading
 stata-cli data --if "price>10000"
 
@@ -312,6 +391,9 @@ describe"
 
 # JSON mode for structured parsing
 stata-cli --json run "display 1+1"
+
+# Export graph as SVG
+stata-cli --graph-format svg run "scatter price mpg"
 ```
 
 ## Contributing

{stata_cli-0.2.2 → stata_cli-0.3.0}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "stata-cli"
-version = "0.2.2"
+version = "0.3.0"
 description = "Command-line interface for running Stata commands via PyStata"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.9"
 license = {text = "MIT"}
 keywords = ["stata", "cli", "statistics", "data-science"]
 

stata_cli-0.3.0/src/stata_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{stata_cli-0.2.2 → stata_cli-0.3.0}/src/stata_cli/daemon.py

@@ -162,6 +162,37 @@ class DaemonServer:
             ok = self._engine.stop()
             _send_msg(conn, {"status": "ok" if ok else "no_op"})
 
+        elif cmd_type == "get_return":
+            data = self._engine.get_return(rtype=payload.get("rtype", "r"))
+            _send_msg(conn, data)
+
+        elif cmd_type == "get_vars":
+            data = self._engine.get_vars()
+            _send_msg(conn, data)
+
+        elif cmd_type == "get_matrix":
+            data = self._engine.get_matrix(payload.get("name", ""))
+            _send_msg(conn, data)
+
+        elif cmd_type == "get_labels":
+            data = self._engine.get_labels(
+                name=payload.get("name"),
+                var=payload.get("var"),
+            )
+            _send_msg(conn, data)
+
+        elif cmd_type == "get_macro":
+            data = self._engine.get_macro(payload.get("name", ""))
+            _send_msg(conn, data)
+
+        elif cmd_type == "set_macro":
+            data = self._engine.set_macro(payload.get("name", ""), payload.get("value", ""))
+            _send_msg(conn, data)
+
+        elif cmd_type == "get_frames":
+            data = self._engine.get_frames()
+            _send_msg(conn, data)
+
         elif cmd_type == "status":
             _send_msg(conn, {
                 "status": "ok",

{stata_cli-0.2.2 → stata_cli-0.3.0}/src/stata_cli/engine.py

@@ -50,14 +50,18 @@ _EXISTING_GRAPHN_RE = re.compile(r"\bname\s*\(\s*graph(\d+)", re.IGNORECASE)
 class StataEngine:
     """Thin wrapper around PyStata for single-process command execution."""
 
-    def __init__(self, stata_path: str, edition: str = "mp", graphs_dir: Optional[str] = None):
+    def __init__(self, stata_path: str, edition: str = "mp", graphs_dir: Optional[str] = None, graph_format: str = "png"):
         self.stata_path = stata_path
         self.edition = edition.lower()
         self.graphs_dir = graphs_dir or get_graphs_root()
+        self.graph_format = graph_format.lower()
         self._stata = None
         self._stlib = None
         self._initialized = False
         self._stop_sent = False
+        self._last_r: dict = {}
+        self._last_e: dict = {}
+        self._last_s: dict = {}
 
     def _ensure_initialized(self) -> None:
         if self._initialized:
@@ -89,6 +93,13 @@ class StataEngine:
 
         self._stata = stata_module
 
+        if self.graph_format != "png":
+            try:
+                from pystata import config as pystata_config  # type: ignore[import-untyped]
+                pystata_config.set_graph_format(self.graph_format)
+            except Exception:
+                pass
+
         try:
             from pystata.config import stlib as stlib_module  # type: ignore[import-untyped]
             self._stlib = stlib_module
@@ -113,19 +124,27 @@ class StataEngine:
         )
         log_file_stata = log_file.replace("\\", "/")
 
-        wrapped = (
+        setup = (
             f'capture log close _all\n'
             f'log using "{log_file_stata}", replace text\n'
-            f'{code}\n'
-            f'capture log close _all\n'
         )
+        teardown = 'capture log close _all\n'
 
         start = time.time()
         try:
             old_stdout = sys.stdout
             sys.stdout = io.StringIO()
             try:
-                self._stata.run(wrapped, echo=True, inline=False)
+                self._stata.run(setup + code, echo=True, inline=False)
+            finally:
+                sys.stdout = old_stdout
+
+            self._capture_stored_results()
+
+            old_stdout = sys.stdout
+            sys.stdout = io.StringIO()
+            try:
+                self._stata.run(teardown, echo=False, inline=False)
             finally:
                 captured_stdout = sys.stdout.getvalue()
                 sys.stdout = old_stdout
@@ -300,6 +319,119 @@ class StataEngine:
 
         return result
 
+    def get_return(self, rtype: str = "r") -> Dict[str, Any]:
+        """Retrieve stored results: r(), e(), or s()."""
+        self._ensure_initialized()
+        try:
+            if rtype == "r":
+                return {"status": "success", "type": "r", "results": dict(self._last_r)}
+            elif rtype == "e":
+                return {"status": "success", "type": "e", "results": dict(self._last_e)}
+            elif rtype == "s":
+                return {"status": "success", "type": "s", "results": dict(self._last_s)}
+            else:
+                return {"status": "error", "error": f"Unknown return type: {rtype}"}
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def get_vars(self) -> Dict[str, Any]:
+        """Return variable metadata for the current dataset."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            nvar = sfi.Data.getVarCount()
+            nobs = sfi.Data.getObsTotal()
+            variables = []
+            for i in range(nvar):
+                name = sfi.Data.getVarName(i)
+                variables.append({
+                    "name": name,
+                    "type": sfi.Data.getVarType(i),
+                    "format": sfi.Data.getVarFormat(i),
+                    "label": sfi.Data.getVarLabel(i),
+                    "is_string": sfi.Data.isVarTypeStr(i),
+                })
+            return {
+                "status": "success",
+                "n_vars": nvar,
+                "n_obs": nobs,
+                "variables": variables,
+            }
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def get_matrix(self, name: str) -> Dict[str, Any]:
+        """Return a Stata matrix as a dict."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            nrows = sfi.Matrix.getRowTotal(name)
+            ncols = sfi.Matrix.getColTotal(name)
+            row_names = sfi.Matrix.getRowNames(name)
+            col_names = sfi.Matrix.getColNames(name)
+            data = sfi.Matrix.get(name)
+            return {
+                "status": "success",
+                "name": name,
+                "rows": nrows,
+                "cols": ncols,
+                "row_names": row_names,
+                "col_names": col_names,
+                "data": data,
+            }
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def get_labels(self, name: Optional[str] = None, var: Optional[str] = None) -> Dict[str, Any]:
+        """Return value labels."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            if var:
+                label_name = sfi.ValueLabel.getVarValueLabel(var)
+                if not label_name:
+                    return {"status": "success", "variable": var, "label_name": "", "labels": {}}
+                mapping = sfi.ValueLabel.getValueLabels(label_name)
+                return {"status": "success", "variable": var, "label_name": label_name, "labels": mapping}
+            if name:
+                mapping = sfi.ValueLabel.getValueLabels(name)
+                return {"status": "success", "name": name, "labels": mapping}
+            names = sfi.ValueLabel.getNames()
+            return {"status": "success", "names": names}
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def get_macro(self, name: str) -> Dict[str, Any]:
+        """Get the value of a Stata macro."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            value = sfi.Macro.getGlobal(name)
+            return {"status": "success", "name": name, "value": value}
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def set_macro(self, name: str, value: str) -> Dict[str, Any]:
+        """Set a Stata global macro."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            sfi.Macro.setGlobal(name, value)
+            return {"status": "success", "name": name, "value": value}
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
+    def get_frames(self) -> Dict[str, Any]:
+        """Return list of Stata frames and the current working frame."""
+        self._ensure_initialized()
+        try:
+            import sfi  # type: ignore[import-untyped]
+            frames = sfi.Frame.getFrames()
+            cwf = sfi.Frame.getCWF()
+            return {"status": "success", "frames": frames, "current": cwf}
+        except Exception as exc:
+            return {"status": "error", "error": str(exc)}
+
     def stop(self) -> bool:
         """Interrupt a running Stata command. Returns True if signal sent."""
         if self._stop_sent or self._stlib is None:
@@ -316,6 +448,44 @@ class StataEngine:
 
     # ── graph detection ──────────────────────────────────────────────────
 
+    def _capture_stored_results(self) -> None:
+        """Snapshot r(), e(), s() results via sfi before log close clears them."""
+        try:
+            import sfi  # type: ignore[import-untyped]
+        except ImportError:
+            return
+
+        for rtype, store in [("r", "_last_r"), ("e", "_last_e"), ("s", "_last_s")]:
+            result: Dict[str, Any] = {}
+            cat = f"{rtype}()"
+            try:
+                scalar_names = sfi.SFIToolkit.listReturn(cat, "scalar")
+                if scalar_names and scalar_names.strip():
+                    for name in scalar_names.strip().split():
+                        try:
+                            result[name] = sfi.Scalar.getValue(f"{rtype}({name})")
+                        except Exception:
+                            pass
+
+                macro_names = sfi.SFIToolkit.listReturn(cat, "macro")
+                if macro_names and macro_names.strip():
+                    for name in macro_names.strip().split():
+                        try:
+                            result[name] = sfi.Macro.getGlobal(f"{rtype}({name})")
+                        except Exception:
+                            pass
+
+                if rtype != "s":
+                    matrix_names = sfi.SFIToolkit.listReturn(cat, "matrix")
+                    if matrix_names and matrix_names.strip():
+                        for name in matrix_names.strip().split():
+                            result[f"matrix:{name}"] = f"[matrix, use 'stata-cli matrix {rtype}({name})']"
+            except Exception:
+                pass
+            setattr(self, store, result)
+
+    # ── graph detection (continued) ─────────────────────────────────────
+
     def _reset_graph_tracking(self) -> None:
         if self._stlib is None:
             return
@@ -348,12 +518,15 @@ class StataEngine:
                     self._stlib.StataSO_Execute(
                         get_encode_str(f"quietly graph display {gname}"), False
                     )
-                    graph_file = os.path.join(batch["batch_dir"], f"{gname}.png")
+                    ext = self.graph_format
+                    graph_file = os.path.join(batch["batch_dir"], f"{gname}.{ext}")
                     graph_file_stata = graph_file.replace("\\", "/")
+                    fmt_opt = f"as({ext}) " if ext != "png" else ""
+                    size_opt = "width(800) height(600)" if ext == "png" else ""
                     export_cmd = (
                         f'quietly graph export "{graph_file_stata}", '
-                        f"name({gname}) replace width(800) height(600)"
-                    )
+                        f"{fmt_opt}name({gname}) replace {size_opt}"
+                    ).rstrip()
                     rc = self._stlib.StataSO_Execute(get_encode_str(export_cmd), False)
                     if rc != 0:
                         continue

{stata_cli-0.2.2 → stata_cli-0.3.0}/src/stata_cli/main.py

@@ -1,4 +1,5 @@
 """Stata CLI - run Stata commands from the terminal."""
+from __future__ import annotations
 
 import json
 import os
@@ -36,8 +37,10 @@ def _exit(code: int) -> None:
 @click.option("--max-tokens", type=int, default=0, help="Max output tokens (0=unlimited). Saves full output to file when exceeded.")
 @click.option("--no-daemon", is_flag=True, default=False, help="Force direct execution, skip daemon.")
 @click.option("--graphs-dir", envvar="STATA_CLI_GRAPHS_DIR", default=None, help="Graph export directory.")
+@click.option("--graph-format", type=click.Choice(["png", "svg", "pdf"], case_sensitive=False), default="png", help="Graph export format.")
+@click.option("--log", "log_file", default=None, help="Save Stata output to a log file.")
 @click.pass_context
-def cli(ctx, stata_path, edition, compact, use_json, timeout, max_tokens, no_daemon, graphs_dir):
+def cli(ctx, stata_path, edition, compact, use_json, timeout, max_tokens, no_daemon, graphs_dir, graph_format, log_file):
     """Command-line interface for Stata."""
     ctx.ensure_object(dict)
     ctx.obj["stata_path"] = stata_path
@@ -48,6 +51,8 @@ def cli(ctx, stata_path, edition, compact, use_json, timeout, max_tokens, no_dae
     ctx.obj["max_tokens"] = max_tokens
     ctx.obj["no_daemon"] = no_daemon
     ctx.obj["graphs_dir"] = graphs_dir
+    ctx.obj["graph_format"] = graph_format
+    ctx.obj["log_file"] = log_file
 
 
 def _get_engine(ctx) -> StataEngine:
@@ -57,7 +62,7 @@ def _get_engine(ctx) -> StataEngine:
         click.echo("Set --stata-path or the STATA_PATH environment variable.", err=True)
         _exit(EXIT_INIT_FAILURE)
     try:
-        engine = StataEngine(stata_path, ctx.obj["edition"], graphs_dir=ctx.obj.get("graphs_dir"))
+        engine = StataEngine(stata_path, ctx.obj["edition"], graphs_dir=ctx.obj.get("graphs_dir"), graph_format=ctx.obj.get("graph_format", "png"))
         return engine
     except Exception as exc:
         click.echo(f"Error initializing Stata: {exc}", err=True)
@@ -89,7 +94,25 @@ def _try_daemon(ctx, cmd_type: str, payload: dict) -> Result | None:
         return None
 
 
-def _print_result(result, compact: bool, use_json: bool = False, max_tokens: int = 0, filter_echo: bool = False) -> None:
+def _try_daemon_dict(ctx, cmd_type: str, payload: dict) -> dict | None:
+    """Try to route a dict-returning command through daemon. Returns None if unavailable."""
+    if ctx.obj.get("no_daemon"):
+        return None
+    try:
+        from .daemon import DaemonClient
+        client = DaemonClient()
+        if not client.is_running():
+            return None
+        if not client.connect():
+            return None
+        resp = client.send(cmd_type, payload)
+        client.close()
+        return resp
+    except Exception:
+        return None
+
+
+def _print_result(result, compact: bool, use_json: bool = False, max_tokens: int = 0, filter_echo: bool = False, log_file: str = None) -> None:
     output = result.output
     if output:
         output = clean_log_wrapper(output)
@@ -112,6 +135,13 @@ def _print_result(result, compact: bool, use_json: bool = False, max_tokens: int
     if graphs:
         for g in graphs:
             click.echo(f"[graph] {g.get('name', 'graph')}: {g.get('path', '')}")
+    if log_file and output:
+        try:
+            with open(log_file, "a", encoding="utf-8") as fh:
+                fh.write(output + "\n")
+            click.echo(f"[log] Output appended to: {log_file}")
+        except OSError as exc:
+            click.echo(f"[log] Failed to write log: {exc}", err=True)
     if not result.success:
         if result.error:
             click.echo(result.error, err=True)
@@ -144,7 +174,7 @@ def run(ctx, code):
     if result is None:
         engine = _get_engine(ctx)
         result = engine.run(code, timeout=ctx.obj["timeout"])
-    _print_result(result, ctx.obj["compact"], use_json=ctx.obj["json"], max_tokens=ctx.obj["max_tokens"])
+    _print_result(result, ctx.obj["compact"], use_json=ctx.obj["json"], max_tokens=ctx.obj["max_tokens"], log_file=ctx.obj.get("log_file"))
 
 
 @cli.command("do")
@@ -162,7 +192,7 @@ def do_file(ctx, path):
     if result is None:
         engine = _get_engine(ctx)
         result = engine.run_file(path, timeout=ctx.obj["timeout"])
-    _print_result(result, ctx.obj["compact"], use_json=ctx.obj["json"], max_tokens=ctx.obj["max_tokens"], filter_echo=True)
+    _print_result(result, ctx.obj["compact"], use_json=ctx.obj["json"], max_tokens=ctx.obj["max_tokens"], filter_echo=True, log_file=ctx.obj.get("log_file"))
 
 
 @cli.command()
@@ -248,6 +278,134 @@ def stop_cmd(ctx):
     _exit(EXIT_USAGE_ERROR)
 
 
+@cli.command("return")
+@click.argument("rtype", type=click.Choice(["r", "e", "s"], case_sensitive=False), default="r")
+@click.pass_context
+def return_cmd(ctx, rtype):
+    """Show stored Stata results (r/e/s).
+
+    \b
+    Examples:
+      stata-cli return r       # r() results after a command
+      stata-cli return e       # e() results after estimation
+      stata-cli return s       # s() results
+    """
+    resp = _try_daemon_dict(ctx, "get_return", {"rtype": rtype.lower()})
+    if resp is None:
+        engine = _get_engine(ctx)
+        resp = engine.get_return(rtype.lower())
+    click.echo(json.dumps(resp, ensure_ascii=False, indent=2))
+
+
+@cli.command("vars")
+@click.argument("names", nargs=-1)
+@click.pass_context
+def vars_cmd(ctx, names):
+    """Show variable metadata for the current dataset.
+
+    \b
+    Examples:
+      stata-cli vars                # all variables
+      stata-cli vars price mpg      # specific variables
+    """
+    resp = _try_daemon_dict(ctx, "get_vars", {})
+    if resp is None:
+        engine = _get_engine(ctx)
+        resp = engine.get_vars()
+
+    if names and resp.get("status") == "success":
+        name_set = set(names)
+        resp["variables"] = [v for v in resp.get("variables", []) if v["name"] in name_set]
+        resp["n_vars"] = len(resp["variables"])
+
+    click.echo(json.dumps(resp, ensure_ascii=False, indent=2))
+
+
+@cli.command("matrix")
+@click.argument("name")
+@click.pass_context
+def matrix_cmd(ctx, name):
+    """Show a Stata matrix.
+
+    \b
+    Examples:
+      stata-cli matrix e(b)        # coefficient vector
+      stata-cli matrix e(V)        # variance-covariance matrix
+      stata-cli matrix r(table)    # results table
+    """
+    resp = _try_daemon_dict(ctx, "get_matrix", {"name": name})
+    if resp is None:
+        engine = _get_engine(ctx)
+        resp = engine.get_matrix(name)
+    click.echo(json.dumps(resp, ensure_ascii=False, indent=2))
+
+
+@cli.command("labels")
+@click.argument("name", required=False, default=None)
+@click.option("--var", default=None, help="Show value label attached to a variable.")
+@click.pass_context
+def labels_cmd(ctx, name, var):
+    """Show value labels.
+
+    \b
+    Examples:
+      stata-cli labels               # list all value label names
+      stata-cli labels origin         # show label-value mapping
+      stata-cli labels --var foreign  # show label for a variable
+    """
+    resp = _try_daemon_dict(ctx, "get_labels", {"name": name, "var": var})
+    if resp is None:
+        engine = _get_engine(ctx)
+        resp = engine.get_labels(name=name, var=var)
+    click.echo(json.dumps(resp, ensure_ascii=False, indent=2))
+
+
+@cli.command("macro")
+@click.argument("action", type=click.Choice(["get", "set"], case_sensitive=False))
+@click.argument("name")
+@click.argument("value", required=False, default=None)
+@click.pass_context
+def macro_cmd(ctx, action, name, value):
+    """Get or set a Stata macro.
+
+    \b
+    Examples:
+      stata-cli macro get "c(current_date)"
+      stata-cli macro get "e(cmd)"
+      stata-cli macro set myvar "hello world"
+    """
+    if action.lower() == "set":
+        if value is None:
+            click.echo("Error: value is required for 'set'.", err=True)
+            _exit(EXIT_USAGE_ERROR)
+        resp = _try_daemon_dict(ctx, "set_macro", {"name": name, "value": value})
+        if resp is None:
+            engine = _get_engine(ctx)
+            resp = engine.set_macro(name, value)
+    else:
+        resp = _try_daemon_dict(ctx, "get_macro", {"name": name})
+        if resp is None:
+            engine = _get_engine(ctx)
+            resp = engine.get_macro(name)
+    click.echo(json.dumps(resp, ensure_ascii=False, indent=2))
+
+
+@cli.command("frame")
+@click.pass_context
+def frame_cmd(ctx):
+    """List Stata frames and the current working frame.
+
+    \b
+    Examples:
+      stata-cli frame
+    """
+    resp = _try_daemon_dict(ctx, "get_frames", {})
+    if resp is None:
+        engine = _get_engine(ctx)
+        resp = engine.get_frames()
+    click.echo(json.dumps(resp, ensure_ascii=False, indent=2))
+
+
 # ── Daemon subcommands ───────────────────────────────────────────────────
 
 @cli.group()

{stata_cli-0.2.2 → stata_cli-0.3.0}/src/stata_cli/utils.py

@@ -1,4 +1,5 @@
 """Platform detection and Stata path auto-discovery."""
+from __future__ import annotations
 
 import os
 import platform

{stata_cli-0.2.2 → stata_cli-0.3.0}/src/stata_cli.egg-info/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: stata-cli
-Version: 0.2.2
+Version: 0.3.0
 Summary: Command-line interface for running Stata commands via PyStata
 License: MIT
 Keywords: stata,cli,statistics,data-science
-Requires-Python: >=3.10
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: click>=8.0
 Provides-Extra: data
@@ -13,8 +13,10 @@ Requires-Dist: pandas; extra == "data"
 
 # stata-cli
 
+![stata-cli banner](assets/banner.png)
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://www.python.org/)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.9-blue.svg)](https://www.python.org/)
 [![npm version](https://img.shields.io/npm/v/stata-cli.svg)](https://www.npmjs.com/package/stata-cli)
 
 [中文版](README.zh.md) | [English](README.md)
@@ -39,10 +41,16 @@ A command-line interface for [Stata](https://www.stata.com/) via PyStata — bui
 | **Run Code** | Execute inline Stata code, multi-line blocks, or pipe from stdin |
 | **Do Files** | Run `.do` files with `///` line continuation support and graph auto-naming |
 | **Data Viewer** | View current dataset as JSON with `if`-condition filtering and row limits |
+| **Variable Metadata** | Inspect variable names, types, formats, and labels via `vars` |
+| **Stored Results** | Retrieve r(), e(), s() results as structured JSON via `return` |
+| **Matrix Access** | Read Stata matrices (e.g. `e(b)`, `e(V)`) as JSON via `matrix` |
+| **Value Labels** | List and inspect value labels via `labels` |
+| **Macro Access** | Get/set Stata macros including `c()`, `e()`, `r()` system macros |
+| **Frame Management** | List Stata frames and current working frame via `frame` |
 | **Help System** | Browse Stata help topics with SMCL-to-plain-text conversion |
-| **Graph Export** | Auto-detect and export graphs as PNG to `~/.stata-cli/graphs/` |
+| **Graph Export** | Auto-detect and export graphs as PNG/SVG/PDF to `~/.stata-cli/graphs/` |
 | **Daemon Mode** | Persistent background process for sub-second execution via Unix socket |
-| **Output Control** | Compact mode, JSON output, token limit management with full-output file save |
+| **Output Control** | Compact mode, JSON output, token limit management, log file output |
 | **Interruption** | Send break signal to stop long-running commands |
 
 ## Installation & Quick Start
@@ -50,7 +58,7 @@ A command-line interface for [Stata](https://www.stata.com/) via PyStata — bui
 ### Requirements
 
 - **Stata 17+** installed on your machine (provides the PyStata library)
-- Python 3.10+
+- Python 3.9+
 
 ### Quick Start (Human Users)
 
@@ -197,6 +205,60 @@ stata-cli detect
 
 Prints the auto-detected Stata installation path.
 
+### `return` — Retrieve Stored Results
+
+```bash
+stata-cli return r         # r() results (after summarize, etc.)
+stata-cli return e         # e() results (after regress, etc.)
+stata-cli return s         # s() results
+```
+
+Returns r(), e(), or s() stored results as structured JSON — scalars, macros, and matrix references.
+
+### `vars` — Variable Metadata
+
+```bash
+stata-cli vars                # all variables
+stata-cli vars price mpg      # specific variables
+```
+
+Returns variable names, types, formats, and labels as JSON. More structured than `describe`.
+
+### `matrix` — Read Stata Matrices
+
+```bash
+stata-cli matrix e(b)         # coefficient vector
+stata-cli matrix e(V)         # variance-covariance matrix
+```
+
+Returns matrix data, dimensions, and row/column names as JSON.
+
+### `labels` — Value Labels
+
+```bash
+stata-cli labels               # list all value label names
+stata-cli labels origin        # show value-label mapping
+stata-cli labels --var foreign # show label attached to a variable
+```
+
+### `macro` — Get/Set Macros
+
+```bash
+stata-cli macro get "c(current_date)"
+stata-cli macro get "e(cmd)"
+stata-cli macro set myvar "hello"
+```
+
+Access Stata macros including system macros (`c()`, `e()`, `r()`).
+
+### `frame` — List Frames
+
+```bash
+stata-cli frame
+```
+
+Shows all Stata frames and the current working frame.
+
 ## Daemon Mode
 
 The daemon keeps PyStata alive in the background — reduces execution time from **~2-3s to ~85ms** (35x speedup).
@@ -234,6 +296,8 @@ The daemon auto-shuts down after 1 hour of inactivity (configurable with `--idle
 | `--max-tokens N` | Max output tokens (0=unlimited) | 0 |
 | `--no-daemon` | Force direct execution | off |
 | `--graphs-dir PATH` | Graph export directory | `~/.stata-cli/graphs/` |
+| `--graph-format [png\|svg\|pdf]` | Graph export format | `png` |
+| `--log PATH` | Save output to a log file | off |
 
 ### JSON Output
 
@@ -313,6 +377,21 @@ regress price mpg weight
 predict yhat
 list make price yhat in 1/5"
 
+# Retrieve regression results as structured JSON
+stata-cli return e
+
+# Get coefficient matrix
+stata-cli matrix e(b)
+
+# Inspect variable metadata
+stata-cli vars price mpg weight
+
+# Check value labels
+stata-cli labels --var foreign
+
+# Read system macros
+stata-cli macro get "c(N)"
+
 # Check data after loading
 stata-cli data --if "price>10000"
 
@@ -325,6 +404,9 @@ describe"
 
 # JSON mode for structured parsing
 stata-cli --json run "display 1+1"
+
+# Export graph as SVG
+stata-cli --graph-format svg run "scatter price mpg"
 ```
 
 ## Contributing

stata_cli-0.2.2/src/stata_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.2.2"