Skip to main content

CLI Reference

Complete command-line interface reference for Upsilon.

upsilon​

Main command for the Upsilon AI code review tool.

upsilon [OPTIONS] COMMAND [ARGS]...

Global Options​

  • --help: Show help message and exit
  • --version: Show version and exit

Commands​

review​

Review code files using AI analysis.

upsilon review [OPTIONS] [FILES]...

Arguments​

  • FILES: Files or directories to review (optional if using --stdin)

Options​

  • --config, -c PATH: Path to configuration file (default: pyproject.toml)
  • --format, -f FORMAT: Output format (choices: text, json) (default: text)
  • --mock/--real: Use mock LLM for testing vs real Claude API (default: real)
  • --verbose, -v: Enable verbose output
  • --stdin: Read file paths from standard input
  • --help: Show help for this command

Examples​

# Review a single file
upsilon review src/main.py

# Review multiple files
upsilon review src/main.py src/utils.py

# Review all Python files in a directory
upsilon review src/*.py

# Review with verbose output
upsilon review src/main.py --verbose

# Review with JSON output
upsilon review src/main.py --format=json

# Review using mock mode for testing
upsilon review src/main.py --mock

# Review with custom config
upsilon review src/main.py --config=custom.toml

# Review files from stdin
find src -name "*.py" | upsilon review --stdin

# Review with pipeline
echo "src/main.py" | upsilon review --stdin --format=json | jq .

Exit Codes​

  • 0: No issues found or only info-level issues
  • 1: Warnings found
  • 2: Errors found
  • 3: Tool execution failed or system error

config-info​

Display current configuration information.

upsilon config-info [OPTIONS]

Options​

  • --config, -c PATH: Path to configuration file (default: pyproject.toml)
  • --help: Show help for this command

Example​

upsilon config-info

Output​

Configuration loaded from: pyproject.toml

Model: claude-3-haiku-20240307
Max tokens: 2000
Temperature: 0.1

Built-in tools:
✓ spell_check (enabled)
✓ syntax_check (enabled)
✓ import_analysis (enabled)

External tools detected:
✓ mypy (available)
✓ ruff (available)
✗ eslint (not found)

Rules:
✓ check_typos
✓ check_logic
✓ check_security
✓ check_style
✓ check_imports

Supported languages: python, javascript, typescript, go, rust, julia, c, cpp

list-tools​

List all available analysis tools.

upsilon list-tools [OPTIONS]

Options​

  • --help: Show help for this command

Example​

upsilon list-tools

Output​

Built-in Tools:
spell_check - Detects common typos in comments and strings
syntax_check - Basic syntax validation using language compilers
import_analysis - Basic import pattern checking

External Tools:
mypy - Python static type checking (✓ available)
ruff - Python linting and formatting (✓ available)
python_compile - Python syntax validation (✓ available)
eslint - JavaScript/TypeScript linting (✗ not found)
rustc - Rust compilation checking (✗ not found)
go_compile - Go compilation checking (✗ not found)
julia_compile - Julia syntax validation (✗ not found)

Configuration File​

The configuration file is typically pyproject.toml in your project root:

[tool.upsilon]
model = "claude-3-haiku-20240307"
max_tokens = 2000
temperature = 0.1

[tool.upsilon.builtin-tools]
spell_check = { enabled = true, language = "en" }
syntax_check = { enabled = true }
import_analysis = { enabled = true }

[tool.upsilon.rules]
check_typos = true
check_logic = true
check_security = true
check_style = true
check_imports = true

ignore_patterns = [
"*.min.js",
"node_modules/*",
".git/*"
]

Environment Variables​

  • ANTHROPIC_API_KEY: API key for Anthropic Claude (required for --real mode)
  • UPSILON_DEBUG: Enable debug logging (set to 1)
  • UPSILON_CONFIG: Default configuration file path

Output Formats​

Text Format (Default)​

Human-readable output with colors and formatting:

📋 Review Results
├── main.py (python) - ✅ No issues
│ ├── Code review for src/main.py (python): No issues found. Code looks good!
│ └── 💡 Recommendations
│ └── Keep up the good work!
└── utils.py (python) - ⚠️ 2 warnings
├── 🔍 Issues
│ ├── Line 15: Unused import 'sys' (ruff)
│ └── Line 23: Function missing docstring (style)
└── 💡 Recommendations
├── Remove unused imports to clean up code
└── Add docstrings for better documentation

JSON Format​

Machine-readable output for automation:

[
{
"file_path": "src/main.py",
"language": "python",
"issues": [],
"summary": "No issues found. Code looks good!",
"overall_score": 10,
"recommendations": ["Keep up the good work!"],
"tool_results": [],
"content_length": 245,
"line_count": 12
},
{
"file_path": "src/utils.py",
"language": "python",
"issues": [
{
"type": "unused_import",
"message": "Unused import 'sys'",
"severity": "warning",
"line": 15,
"column": 8,
"tool": "ruff"
},
{
"type": "missing_docstring",
"message": "Function missing docstring",
"severity": "warning",
"line": 23,
"tool": "style"
}
],
"summary": "2 warnings found",
"overall_score": 8,
"recommendations": [
"Remove unused imports to clean up code",
"Add docstrings for better documentation"
],
"tool_results": [
{
"tool_name": "ruff",
"success": true,
"issues": [
{
"type": "unused_import",
"message": "Unused import 'sys'",
"line": 15
}
]
}
],
"content_length": 1543,
"line_count": 67
}
]

Pipeline Usage​

Upsilon works well in command pipelines:

# Find and review all Python files
find src -name "*.py" | upsilon review --stdin --format=json

# Review only modified files in git
git diff --name-only | grep "\.py$" | upsilon review --stdin

# Review and filter for errors only
upsilon review src/ --format=json | jq '.[] | select(.issues[].severity == "error")'

# Count issues by severity
upsilon review src/ --format=json | jq '.[] | .issues[] | .severity' | sort | uniq -c

# Get overall score statistics
upsilon review src/ --format=json | jq '.[] | .overall_score' | awk '{sum+=$1; count++} END {print "Average score:", sum/count}'

Integration Examples​

GitHub Actions​

- name: Run Upsilon Review
run: |
upsilon review src/ --format=json --real > review_results.json
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

- name: Parse Results
run: |
ERROR_COUNT=$(jq '.[] | .issues[] | select(.severity == "error")' review_results.json | wc -l)
if [ $ERROR_COUNT -gt 0 ]; then
echo "Found $ERROR_COUNT errors"
exit 1
fi

Pre-commit​

repos:
- repo: https://github.com/user/upsilon
rev: v1.0.0
hooks:
- id: upsilon
args: ['--mock', '--format=text']

Make Target​

review:
upsilon review src/ --verbose

review-json:
upsilon review src/ --format=json > review_results.json

review-errors:
upsilon review src/ --format=json | jq '.[] | select(.issues[].severity == "error")'

Performance Tips​

  1. Use mock mode for development: Much faster than API calls
  2. Limit file scope: Review only changed files when possible
  3. Use appropriate output format: JSON for automation, text for humans
  4. Configure ignore patterns: Skip unnecessary files
  5. Adjust token limits: Lower limits for faster processing

Troubleshooting​

Common command-line issues:

# Check if Upsilon is installed
upsilon --version

# Verify configuration
upsilon config-info

# Test with minimal example
echo "print('hello')" | upsilon review --stdin --mock

# Debug with verbose output
upsilon review --verbose --mock problematic_file.py

# Check tool availability
upsilon list-tools