Troubleshooting

sigil: command not found

The Sigil binary is not in your PATH. Check whether it exists at /usr/local/bin/sigil; if not, copy it there or add its install directory to your PATH.

# Check the binary location
ls -la /usr/local/bin/sigil

# Copy it manually if needed
sudo cp ./sigil /usr/local/bin/sigil

# Or add the install directory to PATH
export PATH="$HOME/.sigil/bin:$PATH"

# For Homebrew installs, reload the shell environment
eval "$(brew shellenv)"

Permission denied on install

Installing to /usr/local/bin requires elevated permissions. Either use sudo or install to a user-owned directory instead.

# Option 1: install with sudo
sudo curl -sSL https://sigilsec.ai/install.sh | sh

# Option 2: install to ~/bin (no sudo needed)
mkdir -p ~/bin
curl -sSL https://sigilsec.ai/install.sh | INSTALL_DIR=~/bin sh
export PATH="$HOME/bin:$PATH"

Shell aliases not loading after sigil aliases

Alias definitions are written to your shell config file, but the current session doesn't pick them up until you reload.

# Reload your shell config
source ~/.bashrc   # bash
source ~/.zshrc    # zsh

# Verify the alias exists
alias gclone

# Check the alias was written
grep -n "SIGIL ALIASES" ~/.bashrc ~/.zshrc

Homebrew formula not found

The Sigil formula lives in the NOMARJ tap. You need to add the tap before installing.

brew tap nomarj/tap && brew install sigil

False positives

Sigil flags code patterns that could be malicious. In legitimate projects these patterns are intentional. Suppress known safe patterns with a .sigilignore file. If you believe a finding is a true false positive, report it at github.com/NOMARJ/sigil/issues with the false-positive label.

# Ignore test fixtures
tests/fixtures/
test_data/

# Ignore vendored code
vendor/

Scan takes too long

Large directories with generated or vendored files slow down scanning. Exclude them with a .sigilignore file, limit the scan to specific phases, or raise the severity threshold.

node_modules/
vendor/
dist/
build/
.next/
__pycache__/

# Scan only specific phases
sigil scan . --phases install_hooks,code_patterns

# Raise the severity threshold
sigil scan . --severity high

sigil scan exits with error

Sigil depends on standard Unix tools. Make sure grep, find, and file are installed and available. Run the built-in config check and verify the target path exists.

# Check required tools
which grep find file

# Run config diagnostics
sigil config

# Verify the target path exists
ls -la ./my-project

External scanner not detected

Sigil can optionally use external scanners for deeper analysis. Install the ones you need and verify they appear in the config output.

# Install external scanners
pip install semgrep
pip install bandit
pip install safety
brew install trufflehog

# Verify Sigil detects them
sigil config

No findings but expected some

Sigil scans a specific set of file types: .py, .js, .mjs, .ts, .tsx, .jsx, .sh, .yaml, .yml, .json, and .toml. Check that your target contains supported file types, verify they aren't excluded by .sigilignore, and try lowering the severity threshold.

# Try with the lowest severity threshold
sigil scan . --severity low

sigil login fails

First check network connectivity to the Sigil API. Then verify any custom API URL and your credentials.

# Check API health
curl -s https://api.sigil.nomark.dev/health

# Check your config for a custom API URL
sigil config

# Re-attempt login
sigil login

Token expired

Sigil uses JWT tokens that expire after a set period. When the token expires the CLI falls back to offline mode silently. Re-authenticate to restore cloud features.

sigil login

Threat intelligence not loading

Cloud threat intelligence requires a valid authentication token. Check that your token exists and is still valid.

# Check token status
sigil config

# Verify the token file
cat ~/.sigil/token

# Re-authenticate
sigil logout && sigil login

GitHub Action fails to install

Make sure you're pinning a valid action version and that the runner has the required system tools.

- uses: NOMARJ/sigil@main     # or @v0.9.0 for a pinned release
  with:
    severity: high

The runner must have grep, find, file, git, and curl installed. All GitHub-hosted runners include these by default.

SARIF upload rejected

GitHub rejects SARIF files that are malformed or exceed 10 MB. Validate the output before uploading.

# Generate and validate SARIF
sigil scan . --format sarif > results.sarif
cat results.sarif | python -m json.tool

# Check file size (must be under 10 MB)
ls -lh results.sarif

Exit code mapping

Sigil maps verdicts to exit codes so CI pipelines can gate on severity. Use the table below to configure pass/fail thresholds.

Example gate script for CI pipelines:

sigil scan . --format json > results.json
EXIT_CODE=$?

case $EXIT_CODE in
  0) echo "LOW RISK — deploying" ;;
  4) echo "LOW risk — deploying with warning" ;;
  3) echo "MEDIUM risk — review required"; exit 1 ;;
  2) echo "HIGH risk — blocking deployment"; exit 1 ;;
  1) echo "CRITICAL or error — blocking deployment"; exit 1 ;;
esac

VS Code

The VS Code extension requires the Sigil binary to be available on your PATH. If it can't find the binary, set the path explicitly in settings.

# Check sigil is in PATH
which sigil

# If not, set the Binary Path in VS Code settings:
# Settings > Extensions > Sigil > Binary Path
# e.g. /usr/local/bin/sigil

# Then reload the window
# Cmd+Shift+P > "Developer: Reload Window"

JetBrains

The Sigil JetBrains plugin requires version 2024.1 or later. Update your IDE if you're on an older release.

MCP server not connecting

The MCP server bridges AI agents to the Sigil scanner. If it won't connect, check the config file path, build the server, and verify the Sigil binary is accessible.

# Check MCP config file path
cat ~/.config/sigil/mcp.json

# Build the MCP server
cd plugins/mcp-server && npm install && npm run build

# Verify sigil binary is accessible from the MCP server process
which sigil