stata-cli

Stata CLI Is All Reg Monkeys Need

中文版 | English

A command-line interface for Stata via PyStata — built for humans and AI Agents. Run Stata code, .do files, view data, get help, and export graphs, all from the terminal. Includes a daemon mode for sub-second execution.

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

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.

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

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).

Advanced Usage

Global Options

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": {}
}

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

Exit Codes

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.