Exit Codes

CLI exit codes for scripting and CI integration.

Exit Code Reference

Code	Name	Description
`0`	Success	Analysis completed, score meets threshold
`1`	Failure	Score below threshold or issues found
`2`	Error	Configuration or runtime error

Detailed Descriptions

Exit Code 0 - Success

Analysis completed successfully:

All files analyzed without errors
SEO score meets --min-score threshold
No issues at or above --fail-on severity

capyseo analyze ./dist --ci --min-score 80
echo $?  # 0 (score >= 80)

Exit Code 1 - Failure

Analysis completed but failed checks:

Score below threshold:

capyseo analyze ./dist --ci --min-score 90
# Score: 75/100
echo $?  # 1

Issues above fail-on severity:

capyseo analyze ./dist --ci --fail-on error
# Found 3 errors
echo $?  # 1

Exit Code 2 - Error

Analysis could not complete:

Configuration error:

capyseo analyze ./dist --config invalid.js
echo $?  # 2

File not found:

capyseo analyze ./nonexistent
echo $?  # 2

Invalid options:

capyseo analyze ./dist --format invalid
echo $?  # 2

CI Mode Behavior

In CI mode (--ci), exit codes are strictly enforced:

# Exit 0: score >= 80
capyseo analyze ./dist --ci --min-score 80

# Exit 1: score < 80
capyseo analyze ./dist --ci --min-score 80

# Exit 1: any errors found
capyseo analyze ./dist --ci --fail-on error

Non-CI Mode

Without --ci, exit codes are:

0: Analysis completed (regardless of score)
2: Errors occurred

# Always exit 0 if analysis completes
capyseo analyze ./dist
echo $?  # 0 (even with low score)

Scripting Examples

Bash

#!/bin/bash

capyseo analyze ./dist --ci --min-score 80

case $? in
  0)
    echo "SEO check passed!"
    ;;
  1)
    echo "SEO check failed - score too low"
    exit 1
    ;;
  2)
    echo "SEO check error - configuration issue"
    exit 2
    ;;
esac

With Output Capture

#!/bin/bash

OUTPUT=$(capyseo analyze ./dist --ci --min-score 80 --format json 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "Passed!"
  SCORE=$(echo "$OUTPUT" | jq '.score')
  echo "Score: $SCORE"
elif [ $EXIT_CODE -eq 1 ]; then
  echo "Failed!"
  echo "$OUTPUT" | jq '.issues[] | select(.severity == "error")'
else
  echo "Error: $OUTPUT"
fi

Node.js

import { execSync } from 'child_process';

try {
  const output = execSync('capyseo analyze ./dist --ci --min-score 80', {
    encoding: 'utf8',
  });
  console.log('Passed:', output);
} catch (error) {
  if (error.status === 1) {
    console.log('Failed:', error.stdout);
  } else if (error.status === 2) {
    console.error('Error:', error.stderr);
  }
  process.exit(error.status);
}

GitHub Actions

- name: SEO Analysis
  id: seo
  run: capyseo analyze ./dist --ci --min-score 80
  continue-on-error: true

- name: Check Result
  run: |
    if [ ${{ steps.seo.outcome }} == 'failure' ]; then
      echo "SEO check failed"
      exit 1
    fi

Controlling Exit Codes

--min-score

# Exit 1 if score < 80
capyseo analyze ./dist --ci --min-score 80

# Exit 1 if score < 90 (stricter)
capyseo analyze ./dist --ci --min-score 90

# Never fail on score
capyseo analyze ./dist --ci --min-score 0

--fail-on

# Fail on any issue
capyseo analyze ./dist --ci --fail-on info

# Fail on warnings or errors
capyseo analyze ./dist --ci --fail-on warning

# Fail only on errors
capyseo analyze ./dist --ci --fail-on error

# Don't fail on issues (only score)
capyseo analyze ./dist --ci --fail-on none

Combined

# Fail if score < 80 OR any errors
capyseo analyze ./dist --ci --min-score 80 --fail-on error

# Fail if score < 90 OR any warnings
capyseo analyze ./dist --ci --min-score 90 --fail-on warning

Signal Handling

The CLI handles signals appropriately:

Signal	Behavior
`SIGINT` (Ctrl+C)	Graceful shutdown, exit 130
`SIGTERM`	Graceful shutdown, exit 143
`SIGPIPE`	Ignored (for piping)

# Interrupt during analysis
capyseo analyze ./dist
# Press Ctrl+C
echo $?  # 130 (128 + 2)

Error Messages

Exit code 2 is accompanied by error messages:

# Config error
$ capyseo analyze ./dist --config missing.js
Error: Config file not found: missing.js
$ echo $?
2

# Invalid option
$ capyseo analyze ./dist --format xyz
Error: Invalid format "xyz". Use: console, json, sarif, html, csv
$ echo $?
2

# No files
$ capyseo analyze ./empty
Error: No HTML files found in ./empty
$ echo $?
2

Best Practices

Always use --ci in CI/CD
capyseo analyze ./dist --ci
Set realistic thresholds
--min-score 70 # Start low, increase over time
Fail on errors, warn on warnings
--fail-on error # Critical issues only
Handle all exit codes
if [ $? -eq 0 ]; then # Success elif [ $? -eq 1 ]; then # SEO issues else # Configuration error fi
Log output for debugging
capyseo analyze ./dist --ci 2>&1 | tee seo-log.txt