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, if you installed with INSTALL_DIR=~/bin, add that directory to PATH
export PATH="$HOME/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: let install.sh escalate with sudo when /usr/local/bin is not writable
curl -fsSL https://sigilsec.ai/install.sh | sh

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

Shell aliases not loading after sigil setup shell

sigil setup shell writes gclone, safepip, and safenpm to ~/.zshrc or ~/.bashrc (bash or zsh, detected from $SHELL; other shells get manual instructions), 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

Exit code 2 means the scan itself could not run — an invalid path or flag — never a bad verdict. Verify the target path exists and that the --phases, --severity, and --fail-on values are valid.

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

# Re-run with verbose output
sigil scan ./my-project --verbose

# Print the current configuration
sigil config --list

No findings but expected some

Sigil walks every file under the target, honouring .gitignore (inside git repositories), .sigilignore, and a default exclude list (node_modules, .git, target, .next, __pycache__, .venv, venv, .tox, .mypy_cache, .pytest_cache). Check that the files you expect aren't ignored or excluded, and that you aren't raising the severity threshold.

# Report all severities (low is the default)
sigil scan . --severity low

sigil login fails

First check network connectivity to the Sigil API. Then verify the endpoint you are passing and your credentials.

# Check API health
curl -s https://api.sigilsec.ai/health

# Re-attempt login (defaults to https://api.sigilsec.ai)
sigil login

# Or pass the endpoint explicitly
sigil login --endpoint https://api.sigilsec.ai

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.

# Print the current configuration
sigil config --list

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

# Re-authenticate (there is no logout subcommand — remove the token file)
rm ~/.sigil/token && 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 @v1.3.6 for a pinned release
  with:
    threshold: high

The action installs the binary with install.sh, which needs curl (or wget), and the summary step uses jq. GitHub-hosted runners include these.

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 scan exits 0, 1, or 2. Set the failure threshold with --fail-on (low, medium, high, critical; default high). Exit code 2 means the scan did not produce a verdict — never that the verdict was bad. sigil clone, sigil pip, and sigil npm exit 1 for any verdict other than LOW RISK.

Example gate script for CI pipelines:

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

case $EXIT_CODE in
  0) echo "no findings at or above --fail-on" ;;
  1) echo "findings at or above --fail-on — blocking"; exit 1 ;;
  2) echo "scan error — investigate"; 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 MCP config in your client, build the server, and verify the Sigil binary is accessible (set SIGIL_BINARY if it is not on PATH).

# Check the MCP config your client reads (project .mcp.json, or Claude/Cursor settings)
cat .mcp.json

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

# Verify the sigil binary is accessible from the MCP server process
which sigil
# If it lives elsewhere, set SIGIL_BINARY=/path/to/sigil in the server's env block