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.

return — Retrieve Stored Results

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

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

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

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

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

stata-cli frame

Shows all Stata frames and the current working frame.

skill — Stata Reference Library

stata-cli skill                # overview: gotchas, patterns, topic routing table
stata-cli skill --list         # list all 57 topics with descriptions
stata-cli skill regression     # linear regression reference
stata-cli skill did            # modern DiD packages (csdid, did_multiplegt)
stata-cli skill reghdfe        # reghdfe package guide

Built-in reference library covering data management, econometrics, causal inference, graphics, Mata programming, and 20+ community packages. Aliases supported (e.g. did for difference-in-differences, panel for panel-data).

Daemon Mode

The daemon keeps PyStata alive in the background — reduces execution time from ~2-3s to ~85ms (35x speedup).

stata-cli daemon start       # Start background daemon
stata-cli run "display 1"    # Fast — auto-routes through daemon
stata-cli daemon status      # Check daemon state (PID, uptime, idle)
stata-cli daemon restart     # Clean restart (reset Stata state)
stata-cli daemon stop        # Shut down

Command	Description
daemon start	Start the background daemon process
daemon stop	Graceful shutdown
daemon stop --all	Stop all running sessions
daemon status	Show all running sessions (PID, uptime, idle)
daemon restart	Stop + start (clean Stata state)

Commands auto-route through the daemon when it is running. Use --no-daemon to force direct execution.

The daemon auto-shuts down after 1 hour of inactivity (configurable with --idle-timeout).

Parallel Sessions

Run multiple independent Stata instances — like opening multiple Stata windows:

# Start named sessions
stata-cli --session proj_a daemon start
stata-cli --session proj_b daemon start

# Each session has its own data, estimates, and macros
stata-cli --session proj_a run "use project_a.dta, clear"
stata-cli --session proj_b run "use project_b.dta, clear"

# Route any command to a specific session
stata-cli --session proj_a run "regress price mpg weight"
stata-cli --session proj_b return e

Advanced Usage

Global Options

Option	Description	Default
--stata-path PATH	Stata installation directory	auto-detected
--edition [mp|se|be]	Stata edition	mp
--session NAME	Daemon session name (for parallel sessions)	default
--compact	Strip verbose output noise	off
--json	Structured JSON output	off
--timeout SECONDS	Execution timeout	600
--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

stata-cli --json run "display 1+1"

{
  "success": true,
  "output": ". display 1+1\n2",
  "error": "",
  "execution_time": 0.04,
  "return_code": 0,
  "extra": {}
}

Field	Type	Description
success	bool	Whether the command succeeded
output	string	Stata output text
error	string	Error message (if any)
execution_time	float	Seconds elapsed
return_code	int	Stata r-code (0 = ok)
extra	dict	May contain graphs list with exported file paths

Graph Export

When Stata code creates graphs, they are automatically detected and exported as PNG:

stata-cli run "sysuse auto, clear
scatter price mpg"

[graph] graph1: /Users/you/.stata-cli/graphs/exec-.../graph1.png

In JSON mode, graph paths appear under extra.graphs.

Token Limit Management

For long outputs, use --max-tokens to truncate and save the full output to a file:

stata-cli --max-tokens 500 run "sysuse auto, clear
describe"

When output exceeds the limit, a preview is shown with a path to the full saved output.

Environment Variables

Variable	Description
STATA_PATH	Override Stata installation path
STATA_CLI_GRAPHS_DIR	Override graph export directory

Exit Codes

Code	Meaning
0	Success
1	Stata command error
2	CLI usage error
3	Stata not found / init failure

Agent Usage Pattern

# Full analysis workflow
stata-cli run "sysuse auto, clear
summarize price mpg
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"

# Lookup command syntax
stata-cli help anova

# Compact mode for less noise
stata-cli --compact run "sysuse auto, clear
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

Community contributions are welcome! If you find a bug or have feature suggestions, please submit an Issue or Pull Request.

For major changes, we recommend discussing with us first via an Issue.

License

This project is licensed under the MIT License.