stacy run
Execute a Stata script with error detection
Synopsis
stacy run [SCRIPT] [OPTIONS]
Description
Executes Stata scripts in batch mode and parses log files for errors. Unlike
stata-mp -b, returns proper exit codes that reflect whether the script
succeeded or failed—enabling integration with Make, Snakemake, and CI/CD.
The command runs Stata with -b -q, parses the log for error patterns, and
returns an appropriate exit code (0 for success, 1-10 for various errors).
Program output (boilerplate-stripped) streams to stdout live as Stata writes
it — like Rscript or python — so stacy run foo.do > out.log and pipes
behave as expected. stacy’s own status and error messages go to stderr. On
failure, error details with official Stata documentation links and the log
file path are displayed. Use -v to stream the raw log instead, or -q to
suppress all output.
The batch log file is internal: removed on success, kept on failure with its
path printed in the failure output. Inside a project, kept logs go to [run] log_dir from stacy.toml (logs/ by default); outside one they stay next to
the run. The same rule applies to the scripts run by stacy task, stacy test
and stacy bench, and to every output format — --format json and --format stata report an empty log_file for a run that succeeded, because there is no
log to point at. Use --log <path> to keep the raw Stata log as a durable
artifact — it wins over log_dir and is written whether the run passed or
failed (--quiet --log out.log for a silent file-only run).
Multiple scripts can be run sequentially (default, fail-fast) or in parallel
(--parallel). Parallel mode runs all scripts regardless of failures.
To check a quick result without a script file, use stacy run -c 'display ...'.
In a project with a stacy.lock, run builds the ado-path from the lockfile and
checks it against the package cache before starting Stata. A cached package that
no longer hashes to the checksum the lockfile records fails the run instead of
executing, as does a production package that is not installed at all. dev and
test packages are only checked if they are installed, since stacy install
installs the production group by default. --no-verify skips the check.
Arguments
| Argument | Description |
|---|---|
<SCRIPT> | Script to execute |
Options
| Option | Description |
|---|---|
--allow-global | Allow globally installed packages |
--cache | Enable build cache (skip re-execution if script/deps unchanged) |
--cache-only | Fail if not in cache (useful for CI) |
--cd | Change to script’s parent directory |
-c, --code | Inline Stata code |
-C, --directory | Run Stata in this directory |
--engine | Stata engine to use (overrides config and auto-detection) |
--force | Force rebuild even if cached |
-j, --jobs | Max parallel jobs (default: CPU count) |
--log | Write the raw Stata log to this path |
--no-verify | Skip the check of the package cache against stacy.lock |
-P, --parallel | Run scripts in parallel |
--profile | Include execution metrics |
-q, --quiet | Suppress output |
--timeout | Kill script if it exceeds this many seconds |
--trace | Enable execution tracing at given depth |
--verbose | Extra output |
Examples
Run a script
stacy run analysis.do
Multiple scripts (sequential)
Runs in order, stops on first failure
stacy run clean.do analyze.do report.do
Parallel execution
Run all scripts concurrently for faster execution
stacy run --parallel *.do
stacy run --parallel -j4 a.do b.do c.do
Inline code
Execute Stata code without creating a file
stacy run -c 'display 2+2'
stacy run -c 'sysuse auto, clear
summarize price'
Working directory
Run in a specific directory (script paths resolved before cd)
stacy run -C reports/pilot/ table.do
stacy run --cd reports/pilot/table.do
Verbose output
Stream log file in real-time
stacy run -v long_analysis.do
JSON output
Machine-readable output for CI/CD
stacy run --format json analysis.do
Execution tracing
Enable Stata’s set trace on for debugging
stacy run --trace 2 analysis.do
stacy run --trace 2 -v analysis.do
Timeout
Kill script if it takes longer than 60 seconds
stacy run --timeout 60 long_analysis.do
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Stata error (r() code detected) |
| 2 | Syntax error |
| 3 | File error (not found, permission denied) |
| 4 | Memory error |
| 5 | Internal stacy error |
| 6 | Statistical error (convergence, model problems) |
| 10 | Environment error (Stata not found) |
See Exit Codes Reference for details.