JSON Output

stacy supports JSON output for machine-readable results.

Usage

Add --format json to any command:

stacy run --format json analysis.do
stacy install --format json
stacy env --format json

Output Schemas

stacy run

Success:

{
  "success": true,
  "script": "analysis.do",
  "duration_secs": 12.45,
  "exit_code": 0,
  "log_file": "analysis.log"
}

Failure:

{
  "success": false,
  "script": "analysis.do",
  "duration_secs": 0.45,
  "exit_code": 2,
  "log_file": "analysis.log",
  "errors": [
    {
      "type": "StataCode",
      "r_code": 199,
      "name": "unrecognized command",
      "line": 15,
      "context": "reghdfe price mpg, absorb(make)"
    }
  ]
}

stacy install

{
  "success": true,
  "installed": [
    {
      "name": "estout",
      "version": "2024.03.15",
      "source": "SSC"
    },
    {
      "name": "reghdfe",
      "version": "6.12.3",
      "source": "GitHub"
    }
  ],
  "already_cached": [
    {
      "name": "ftools",
      "version": "2.49.0",
      "source": "SSC"
    }
  ],
  "failed": []
}

stacy list

{
  "packages": [
    {
      "name": "estout",
      "version": "2024.03.15",
      "source": "SSC",
      "locked": true
    },
    {
      "name": "reghdfe",
      "version": "6.12.3",
      "source": "GitHub",
      "locked": true
    }
  ]
}

stacy env

{
  "stata": {
    "binary": "/Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp",
    "version": "18.0",
    "flavor": "MP",
    "source": "user config"
  },
  "project": {
    "root": "/Users/user/projects/analysis",
    "has_config": true,
    "has_lockfile": true
  },
  "cache": {
    "path": "/Users/user/.cache/stacy/packages",
    "package_count": 12
  }
}

stacy doctor

{
  "ready": true,
  "checks": [
    {
      "name": "Stata binary",
      "status": "ok",
      "message": "Found at /Applications/StataNow/StataMP.app/Contents/MacOS/stata-mp"
    },
    {
      "name": "Stata version",
      "status": "ok",
      "message": "Stata 18.0 MP"
    },
    {
      "name": "Project config",
      "status": "ok",
      "message": "Found stacy.toml"
    },
    {
      "name": "Lockfile",
      "status": "warning",
      "message": "No stacy.lock found"
    }
  ]
}

stacy deps

{
  "root": "master.do",
  "files": [
    "master.do",
    "config/settings.do",
    "src/01_clean_data.do",
    "src/utils/helpers.do"
  ],
  "missing": [],
  "circular": []
}

jq Examples

Check if a run succeeded

stacy run --format json analysis.do | jq '.success'

Get exit code

stacy run --format json analysis.do | jq '.exit_code'

Extract error codes

stacy run --format json analysis.do | jq '.errors[]?.r_code'

List installed package names

stacy list --format json | jq -r '.packages[].name'

Get Stata binary path

stacy env --format json | jq -r '.stata.binary'

Check if project has lockfile

stacy env --format json | jq '.project.has_lockfile'

Find failed doctor checks

stacy doctor --format json | jq '.checks[] | select(.status == "error")'

Count dependencies

stacy deps --format json master.do | jq '.files | length'

Get packages that need downloading

stacy install --format json | jq '.installed[].name'

Using JSON in Scripts

Shell

#!/bin/bash
result=$(stacy run --format json analysis.do)
if echo "$result" | jq -e '.success' > /dev/null; then
    echo "Success!"
else
    echo "Failed with errors:"
    echo "$result" | jq -r '.errors[].name'
    exit 1
fi

Python

import subprocess
import json

result = subprocess.run(
    ['stacy', 'run', '--format', 'json', 'analysis.do'],
    capture_output=True,
    text=True
)
data = json.loads(result.stdout)

if data['success']:
    print(f"Completed in {data['duration_secs']:.2f}s")
else:
    for error in data.get('errors', []):
        print(f"Error r({error['r_code']}): {error['name']}")

R

library(jsonlite)

result <- system2("stacy", c("run", "--format", "json", "analysis.do"),
                  stdout = TRUE, stderr = TRUE)
data <- fromJSON(paste(result, collapse = "\n"))

if (data$success) {
  cat(sprintf("Completed in %.2fs\n", data$duration_secs))
} else {
  cat("Errors:\n")
  print(data$errors)
}

Stability

The JSON schema follows semantic versioning:

• Core fields (success, exit_code, errors) are stable from v1.0
• New fields may be added in minor versions (backward compatible)
• Field removal or type changes only in major versions

Tip: Use jq’s -e flag to handle missing fields gracefully in scripts.

See Also

• stacy run - Running scripts
• Build Integration - CI/CD and build tools
• Exit Codes - Exit code meanings