stata-cli

The agent-native Stata CLI for empirical research

中文版 | English

An agent-native command-line interface for Stata via PyStata. Let Codex, Claude Code, Cursor, and other AI coding agents run .do files, inspect datasets, retrieve econometric results as JSON, and export graphs from the terminal. A persistent daemon keeps repeated analyses fast.

Install · AI Agent · Commands · Daemon · Advanced · Contributing

Why stata-cli?

• Agent-Native Design — Structured JSON output, exit codes, and a SKILL.md definition out of the box — AI Agents can operate Stata with zero extra setup
• Sub-Second Execution — Daemon mode keeps PyStata alive in the background, reducing startup from ~2-3s to ~85ms (35x speedup)
• Full Coverage — Run code, execute .do files, view data, browse help, export graphs, interrupt execution — everything you need from one binary
• AI-Friendly & Optimized — Compact output mode, token limit management, structured JSON responses, and graph auto-naming — designed for Agent tool-use
• Open Source, Zero Barriers — MIT license, ready to use, just pip install
• Up and Running in Seconds — Auto-detects your Stata installation, from install to first command in 2 steps

Features

Category	Capabilities
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/SVG/PDF to ~/.stata-cli/graphs/
Daemon Mode	Persistent background process for sub-second execution; parallel sessions via --session
Output Control	Compact mode, JSON output, token limit management, log file output
Interruption	Send break signal to stop long-running commands
Skill Library	Built-in Stata reference with 57 topics: syntax, econometrics, causal inference, packages

Installation & Quick Start

Requirements

• Stata 17+ installed on your machine (provides the PyStata library)
• Python 3.9+

Quick Start (Human Users)

Install

Choose one of the following methods:

Option 1 — From pip (recommended):

pip install stata-cli

Option 2 — From npm / npx (zero Python setup):

# One-shot usage
npx stata-cli run "display 1+1"

# Global install
npm install -g stata-cli

The npm package is a thin wrapper that delegates to uvx, pipx, or python3.

Option 3 — From source:

git clone https://github.com/ashuiGordon/stata-cli.git
cd stata-cli
pip install -e ".[data]"

Use

# 1. Verify Stata is detected
stata-cli detect

# 2. Run your first command
stata-cli run "display 1+1"

# 3. Start daemon for fast execution
stata-cli daemon start
stata-cli run "sysuse auto, clear"    # ~85ms!

Quick Start (AI Agent)

The following steps are for AI Agents calling stata-cli via the Bash tool.

Step 1 — Install

pip install stata-cli

Step 2 — Verify Stata path

stata-cli detect

Step 3 — Start daemon (recommended)

stata-cli daemon start

Step 4 — Run commands

# Inline code
stata-cli run "sysuse auto, clear
regress price mpg weight
predict yhat"

# Structured JSON output
stata-cli --json run "summarize price"

# View data
stata-cli data --if "price>10000" --rows 50

# Lookup command syntax
stata-cli help regress

Commands

run — Execute Stata Code

stata-cli run "sysuse auto, clear"

# Multi-line
stata-cli run "sysuse auto, clear
summarize price mpg
regress price mpg weight"

# Pipe from stdin
echo "display 42" | stata-cli run -

do — Execute a .do File

stata-cli do analysis.do
stata-cli --compact do long_script.do

Do files are preprocessed: /// line continuations are joined, and unnamed graph commands are auto-named for reliable export.

data — View Current Dataset

stata-cli data
stata-cli data --if "price>5000" --rows 50

Returns the current dataset as JSON with columns, data, types, and row counts.

help — Browse Stata Help

stata-cli help regress
stata-cli help summarize

Displays help as plain text (SMCL markup is automatically converted).

stop — Interrupt Execution

stata-cli stop

Sends a break signal to the running Stata command (daemon mode).

detect — Find Stata Installation

stata-cli detect

Prints the auto-detected Stata installation path.

config — Manage Persistent Configuration

stata-cli config list
stata-cli config set stata-path "/path/to/stata"
stata-cli config get stata-path

Stores settings in ~/.stata-cli/config.json (e.g., custom Stata path) to avoid passing flags repeatedly.

This is the beginning of the README. Read the rest at the original. Read the full README ↗