datalab-cli 0.1.0

# Exit Codes

Reference for exit codes returned by the Datalab CLI.

---

## Exit Code Summary

| Code | Meaning | Description |
|------|---------|-------------|
| `0` | Success | Command completed successfully |
| `1` | Error | Command failed |

---

## Exit Code 0: Success

The command completed successfully.

```bash
datalab convert document.pdf
echo $?  # Output: 0
```

**Indicates**:
- Document was processed
- Result was output to stdout
- No errors occurred

---

## Exit Code 1: Error

The command failed.

```bash
datalab convert nonexistent.pdf
echo $?  # Output: 1
```

**Common causes**:
- File not found
- Invalid API key
- Network error
- Rate limit exceeded
- Processing error
- Invalid input

See [Errors Reference](errors.md) for specific error types.

---

## Using Exit Codes

### In Bash Scripts

```bash
#!/bin/bash

if datalab convert document.pdf > result.json; then
    echo "Success!"
    process_result result.json
else
    echo "Failed!"
    exit 1
fi
```

### With set -e

```bash
#!/bin/bash
set -e  # Exit on any error

datalab convert doc1.pdf > result1.json
datalab convert doc2.pdf > result2.json
datalab convert doc3.pdf > result3.json

echo "All conversions successful"
```

### Checking Exit Code Explicitly

```bash
#!/bin/bash

datalab convert document.pdf > result.json
exit_code=$?

case $exit_code in
    0)
        echo "Success"
        ;;
    1)
        echo "Error occurred"
        ;;
    *)
        echo "Unexpected exit code: $exit_code"
        ;;
esac
```

### In Makefiles

```makefile
.PHONY: convert
convert:
	datalab convert document.pdf > result.json

.PHONY: convert-or-warn
convert-or-warn:
	datalab convert document.pdf > result.json || echo "Conversion failed"
```

### In CI/CD Pipelines

```yaml
# GitHub Actions example
steps:
  - name: Convert document
    run: datalab convert document.pdf > result.json

  - name: Process result
    run: process_result result.json
```

The pipeline will fail if the `datalab` command returns exit code 1.

---

## Error Recovery Patterns

### Retry on Failure

```bash
#!/bin/bash

max_retries=3
retry_count=0

while [ $retry_count -lt $max_retries ]; do
    if datalab convert document.pdf > result.json 2>/dev/null; then
        echo "Success"
        exit 0
    fi

    retry_count=$((retry_count + 1))
    echo "Retry $retry_count of $max_retries..."
    sleep 5
done

echo "Failed after $max_retries attempts"
exit 1
```

### Continue on Error

```bash
#!/bin/bash

for file in documents/*.pdf; do
    if datalab convert "$file" > "${file%.pdf}.json" 2>/dev/null; then
        echo "Converted: $file"
    else
        echo "Failed: $file" >> failed.log
    fi
done

if [ -f failed.log ]; then
    echo "Some conversions failed. See failed.log"
    exit 1
fi
```

### Capture Error Details

```bash
#!/bin/bash

output=$(datalab -q convert document.pdf 2>&1)
exit_code=$?

if [ $exit_code -ne 0 ]; then
    error_code=$(echo "$output" | jq -r '.code // "UNKNOWN"')
    error_msg=$(echo "$output" | jq -r '.error // "Unknown error"')

    echo "Error [$error_code]: $error_msg"
    exit 1
fi

echo "$output"
```

---

## Combining with Other Tools

### With xargs

```bash
# Process multiple files, stop on first error
ls documents/*.pdf | xargs -I{} datalab convert {} -o {}.json

# Process all files, ignore errors
ls documents/*.pdf | xargs -I{} sh -c 'datalab convert "$1" -o "$1.json" || true' _ {}
```

### With GNU Parallel

```bash
# Process in parallel, fail if any fails
parallel --halt-on-error 2 'datalab convert {} > {.}.json' ::: documents/*.pdf

# Process in parallel, continue on errors
parallel 'datalab convert {} > {.}.json 2>/dev/null || echo "Failed: {}"' ::: documents/*.pdf
```

### With find

```bash
# Process all PDFs recursively
find . -name "*.pdf" -exec sh -c '
    if datalab convert "$1" > "${1%.pdf}.json"; then
        echo "OK: $1"
    else
        echo "FAIL: $1"
    fi
' _ {} \;
```

---

## See Also

- [Errors Reference](errors.md)
- [Output Formats](../concepts/output-formats.md)
- [Agent Integration](../tutorials/agent-integration.md)