# CLI Reference

Stata-MCP provides a command-line interface (CLI) for various operations including starting MCP servers, running agent mode, and installing to different AI clients.

## Installation

Verify your installation:

```bash
stata-mcp --version
```

Run diagnostics to check system health:

```bash
stata-mcp doctor
```

> **Note:** `--usable` has been deprecated since v1.14.3. It still works in current releases but `stata-mcp doctor` is the recommended replacement in v1.16+ and may be removed in a later major release.

## Commands

### Start MCP Server

Start the MCP server with different transport methods:

```bash
# Start with stdio transport (default)
stata-mcp

# Explicitly specify transport method
stata-mcp -t stdio
stata-mcp -t sse
stata-mcp -t http
```

#### Server Subcommand

Use the `server` subcommand to control which MCP tools are registered:

```bash
# All tools, stdio transport (same as bare command)
stata-mcp server

# Core tools only (stata_do, get_data_info, help)
stata-mcp server --core

# All tools with HTTP transport
stata-mcp server --all -t http

# Core tools with SSE transport
stata-mcp server --core -t sse
```

**Tool Profiles:**
- `--all` - Register all available tools (default)
- `--core` - Register only core tools: `stata_do`, `get_data_info`, `help`

**Transport Options:**
- `stdio` - Standard input/output (default)
- `sse` - Server-Sent Events
- `http` - HTTP transport (automatically converted to streamable-http)

### Agent Mode

> **Deprecated**: Agent mode is marked with `FutureWarning` since v1.16.x and will be removed in a future release. New workflows should use MCP server mode (`stata-mcp server` or `stata-mcp install`).

Run Stata-MCP in interactive agent mode:

```bash
# Start agent in current directory
stata-mcp agent run

# Start agent in specific directory
stata-mcp agent run --work-dir /path/to/project
```

### Doctor Diagnostics

Run health checks to diagnose potential issues:

```bash
# Run all checks
stata-mcp doctor

# Show detailed information for each check
stata-mcp doctor --verbose

# Output in JSON format
stata-mcp doctor --json

# Run only specific checks (repeatable)
stata-mcp doctor --check stata --check python

# Preview cleanup actions without deleting (cleanup checks only)
stata-mcp doctor --check cleanup --dry-run
```

Common check names include `stata`, `python`, and `cleanup`. The `--dry-run` flag is interpreted by cleanup-style checks and previews destructive operations instead of executing them; other checks ignore it.

### Update

Update stata-mcp to the latest version:

```bash
# Auto-detect install method and update
stata-mcp update

# Check if a newer version is available
stata-mcp update --check

# Show detected method and available update without executing
stata-mcp update --dry-run

# Force specific update method
stata-mcp update --method pip       # pip install
stata-mcp update --method uv-tool   # uv tool upgrade
stata-mcp update --method homebrew  # brew upgrade
```

**Update Methods:** `auto` (default), `pip`, `uv-tool`, `homebrew`

> **Note for uv tool users on versions before 1.17.2:** Due to a detection bug in earlier versions, `stata-mcp update` may incorrectly detect pip and fail. Run `uv tool upgrade stata-mcp` once manually to reach 1.17.2 or later, after which `stata-mcp update` will work correctly.

### Local Tool Commands

Run API-backed Stata tools directly from the CLI:

```bash
# Install an ado package from SSC (default source)
stata-mcp tool ado-install reghdfe

# Run a do-file and only read the log when execution fails
stata-mcp tool do /path/to/analysis.do --read-log-when-error true

# Read Stata help through the one-shot API helper
stata-mcp tool help regress --enable-smcl true

# Inspect a supported dataset
stata-mcp tool data-info /path/to/data.dta

# Read a generated log file
stata-mcp tool read-log /path/to/output.log
```

Tool subcommands:
- `stata-mcp tool ado-install <package_name> [--source ssc|net|github]`
- `stata-mcp tool do <dofile_path> [--read-log-when-error true|false] [--enable-smcl true|false]`
- `stata-mcp tool help <command> [--read-log-when-error true|false] [--enable-smcl true|false]`
- `stata-mcp tool data-info <data_path> [--vars-list var1 var2 ...]`
- `stata-mcp tool read-log <log_path> [--output-format full|core|dict]`

> Note: `--read-log-when-error` replaces the older `--is-read-log` flag. Unlike the old flag (which unconditionally read the log), the new flag reads the log only when the underlying execution reports an error.

### Config Management

Inspect and update local CLI configuration stored in `~/.statamcp/config.toml`:

```bash
# Print the entire config file
stata-mcp config

# Show a single value (cli is shorthand for STATA.STATA_CLI)
stata-mcp config show cli
stata-mcp config show STATA.STATA_CLI
stata-mcp config show SECURITY.IS_GUARD

# Set STATA_CLI explicitly
stata-mcp config set cli /path/to/stata

# Auto-detect STATA_CLI via StataFinder and persist it
stata-mcp config set cli

# Edit an existing key by dot-notation
stata-mcp config edit STATA.STATA_CLI /path/to/stata
stata-mcp config edit SECURITY.IS_GUARD false
```

The `set` subcommand currently accepts only the `cli` key. The `edit` subcommand accepts any existing `Section.Key` in the config file and rejects keys that are not already defined.

### Install to AI Clients

Install Stata-MCP to various AI coding assistants:

```bash
# Install to all supported clients (no -c, no --json-file)
stata-mcp install

# Install to a specific client
stata-mcp install -c claude-code
stata-mcp install -c cursor

# Install to all clients explicitly
stata-mcp install --all

# Install into a custom JSON config file
stata-mcp install --json-file /path/to/config.json

# Install into a nested key inside a custom JSON config file
stata-mcp install --json-file /path/to/config.json --json-index mcp.servers
```

**Supported Clients:**

| Client ID | Target | Aliases |
|-----------|--------|---------|
| `claude` | Claude Desktop | |
| `claude-code` | Claude Code | `cc` |
| `cursor` | Cursor Editor | |
| `cline` | Cline (VS Code extension) | |
| `codex` | Codex | |
| `gemini` | Gemini CLI | |
| `opencode` | OpenCode | |
| `openclaw` | OpenClaw | |
| `hermes` | Hermes | `hermes-agent` |

### Docker-based Installation (sandbox-install)

Install Docker-based Stata-MCP to AI clients. Requires Docker and a valid Stata license.

```bash
# Basic usage with default settings (StataNow 19.5 MP)
uvx stata-mcp sandbox-install -l /path/to/stata.lic

# Specify Stata version and edition
uvx stata-mcp sandbox-install \
  --version 19_5 \
  --edition mp \
  -l /path/to/stata.lic \
  -c claude

# With resource limits
uvx stata-mcp sandbox-install \
  -V 18 \
  -e se \
  -l /path/to/stata.lic \
  --cpus 2 \
  --memory 4g
```

**Stata Versions:** `19_5`, `18_5`, `18`

**Stata Editions:** `mp` (Multi-processor), `se` (Standard), `be` (Basic)

## Options

### Server Options

| Option | Description |
|--------|-------------|
| `--core` | Register only core tools (stata_do, get_data_info, help) |
| `--all` | Register all tools (default) |
| `-t`, `--transport` | MCP transport method (stdio/sse/http) |

### Global Options

| Option | Short | Description |
|--------|-------|-------------|
| `--version` | `-v` | Show version information |
| `--help` | `-h` | Show help message |
| `--usable` | `-u` | *(Deprecated)* Check system compatibility, use `stata-mcp doctor` instead |
| `--transport` | `-t` | MCP transport method (stdio/sse/http) |

### Agent Options

| Option | Description |
|--------|-------------|
| `--work-dir` | Working directory for agent (default: current directory) |

### Config Options

| Command | Description |
|---------|-------------|
| `stata-mcp config` | Print the raw `~/.statamcp/config.toml` content |
| `stata-mcp config show <dot_key>` | Show one value. `cli` is shorthand for `STATA.STATA_CLI`; otherwise use `Section.Key` |
| `stata-mcp config set cli [value]` | Set `STATA.STATA_CLI`. Auto-detect via StataFinder when value is omitted |
| `stata-mcp config edit <dot_key> <value>` | Edit an existing `Section.Key` entry |

### Install Options

| Option | Short | Description |
|--------|-------|-------------|
| `--client` | `-c` | Target client. Omitting both `-c` and `--json-file` is equivalent to `--all` |
| `--all` | `-a` | Install to all supported clients |
| `--json-file` | | Custom target client config file path |
| `--json-index` | | Dot-separated nested key path (e.g. `mcp.servers`); only valid together with `--json-file` |

### Doctor Options

| Option | Description |
|--------|-------------|
| `--verbose` | Show detailed information for each check |
| `--json` | Output report in JSON format |
| `--check` | Run only specified check names (repeatable) |
| `--dry-run` | Preview cleanup actions without deleting files (cleanup-style checks only) |

### Update Options

| Option | Description |
|--------|-------------|
| `--method` | Force specific update method (auto/pip/uv-tool/homebrew) |
| `--dry-run` | Show detected method without updating |
| `--check` | Only check if a newer version is available |

### Sandbox-Install Options

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--version` | `-V` | `19_5` | Stata version (19_5, 18_5, 18) |
| `--edition` | `-e` | `mp` | Stata edition (mp, se, be) |
| `--tag` | | `latest` | Docker image tag |
| `--license-file` | `-l` | (required) | Path to Stata license file |
| `--client` | `-c` | `claude` | Target client |
| `--work-dir` | | `./` | Working directory |
| `--cpus` | | (none) | CPU core limit |
| `--memory` | | (none) | Memory limit (e.g., 4g) |

## Examples

### Basic Usage

```bash
# Check if Stata-MCP can run on your system
stata-mcp doctor

# Start MCP server for Claude Desktop
stata-mcp

# Start with SSE transport
stata-mcp -t sse
```

### Development Workflow

```bash
# 1. Run diagnostics
stata-mcp doctor

# 2. Install to Claude Code
stata-mcp install -c claude-code

# 3. Inspect a dataset before writing the analysis
stata-mcp tool data-info /path/to/data.dta
```

### Using with uvx

If you prefer not to install Stata-MCP globally, you can use `uvx`:

```bash
# Check version
uvx stata-mcp --version

# Run diagnostics
uvx stata-mcp doctor

# Run a do-file directly
uvx stata-mcp tool do /path/to/analysis.do

# Start the MCP server
uvx stata-mcp server

# Install to a client
uvx stata-mcp install -c cursor
```

## Self-contained Install Scripts

The project root ships a set of self-contained installer scripts for users who do not already have `uv` or `pip` available. They bootstrap a Python toolchain and bring up `stata-mcp` in one step.

| Script | Target platform | Typical use |
|--------|-----------------|-------------|
| `install.sh` | Unix shells (Linux, macOS, WSL) | `bash install.sh` |
| `install.command` | macOS Finder | double-click to launch in Terminal |
| `install.ps1` | Windows PowerShell | `powershell -ExecutionPolicy Bypass -File install.ps1` |
| `install.bat` | Windows command line | double-click or run from `cmd.exe` |

These scripts are intended for first-time bootstrap on machines without a Python package manager. On machines that already have `uv` or `pip`, the standard `uv tool install stata-mcp` / `pip install stata-mcp` flow is preferred.

## Exit Codes

- `0` - Success
- `1` - Error (invalid client, system incompatibility, etc.)
- `2` - Command line argument error

## Environment Variables

Stata-MCP behavior can be configured through environment variables. See [Configuration](configuration.md) for details.

Key environment variables:

- `STATA_MCP_CWD` - Working directory for Stata operations
- `STATA_MCP_LOGGING_ON` - Enable/disable logging
- `STATA_MCP__IS_GUARD` - Enable security guard validation
- `STATA_MCP__IS_MONITOR` - Enable RAM monitoring

See the [Configuration](configuration.md) document for the complete list.

## Troubleshooting

### "Stata not found" Error

Ensure Stata is installed and accessible:

```bash
stata-mcp doctor
```

This will run diagnostics and check if Stata can be found on your system.

### Permission Errors

Some operations may require appropriate permissions:
- Installing to Claude Desktop may need admin/user privileges
- Working directories must be writable

### Transport Issues

If you encounter issues with specific transport methods:
- Default to `stdio` for most use cases
- Use `--transport stdio` explicitly if auto-detection fails

## See Also

- [Usage Guide](usage.md) - Detailed usage examples
- [Configuration](configuration.md) - Environment variables and settings
- [Security](security.md) - Security guard and validation
- [Monitoring](monitoring.md) - Resource monitoring configuration
