Reference

CLI Reference

Every command, flag, exit code, and scan phase in the Sigil CLI. Eight scan phases run locally — no account required for the open-source tier.

Setup commands

sigil install

Install Sigil and set up the default directory structure under ~/.sigil. Creates the quarantine, approved, logs, and reports directories.

bash

sigil install

# Creates:
#   ~/.sigil/quarantine/
#   ~/.sigil/approved/
#   ~/.sigil/logs/
#   ~/.sigil/reports/
#   ~/.sigil/config

sigil aliases

Output shell alias configuration for your current shell. Adds drop-in replacements that route commands through Sigil's quarantine-first workflow.

bash

# Add to your .bashrc / .zshrc
eval "$(sigil aliases)"

# Preview aliases without writing to shell config
sigil aliases --print

Flag	Description
--print	Print aliases to stdout without modifying shell config

Available aliases:

Alias	Expands to	Description
gclone	sigil clone	Quarantine-first git clone
safepip	sigil pip	Quarantine-first pip install
safenpm	sigil npm	Quarantine-first npm install
safefetch	sigil fetch	Quarantine-first URL fetch
audit	sigil scan	Scan a target
audithere	sigil scan .	Scan the current directory
qls	sigil list	List quarantined items
qapprove	sigil approve	Approve a quarantined item
qreject	sigil reject	Reject a quarantined item

sigil config

View or modify the Sigil configuration. Without flags, prints the current config.

bash

# Print current config
sigil config

# Generate a default config file
sigil config --init

Flag	Description
--init	Generate a default `~/.sigil/config` file with all options documented

sigil hooks

Install git hooks that automatically scan commits and pushes. Adds a pre-commit hook that runs Sigil on staged changes.

bash

sigil hooks

# Installs .git/hooks/pre-commit that runs sigil scan on staged files

Audit commands

sigil clone

Clone a git repository into quarantine, scan it, then move to your workspace if approved. Drop-in replacement for git clone.

bash

sigil clone <repo-url> [directory] [flags]

# Examples
sigil clone https://github.com/user/repo
sigil clone git@github.com:user/repo.git my-folder
sigil clone https://github.com/user/repo --auto-approve=low

sigil pip

Install a Python package into quarantine, scan it, then install to your environment if approved. Drop-in replacement for pip install.

bash

sigil pip <package> [flags]

# Examples
sigil pip requests
sigil pip flask==3.0.0
sigil pip -r requirements.txt

sigil npm

Install an npm package into quarantine, scan it, then install to your project if approved. Drop-in replacement for npm install.

bash

sigil npm <package> [flags]

# Examples
sigil npm express
sigil npm lodash@4.17.21
sigil npm --save-dev typescript

sigil scan

Scan a package, directory, or URL. Runs all six analysis phases and outputs a verdict with a risk score.

bash

sigil scan <target> [flags]

# Examples
sigil scan npm:express
sigil scan pypi:requests
sigil scan ./local-directory
sigil scan https://github.com/user/repo

sigil fetch

Download a URL into quarantine, scan it, then move to your workspace if approved. Works with tarballs, zip archives, and raw files.

bash

sigil fetch <url> [flags]

# Examples
sigil fetch https://example.com/package.tar.gz
sigil fetch https://example.com/script.sh

Quarantine management

sigil list

List all items currently in quarantine. Shows the scan verdict, score, and timestamp for each item.

bash

sigil list

# Example output:
#   ID       TARGET              SCORE  VERDICT      DATE
#   q_01a..  npm:express@4.18.2  0      LOW RISK     2025-01-15
#   q_02b..  pypi:requests       3      LOW RISK     2025-01-15
#   q_03c..  github.com/u/repo   27     HIGH RISK    2025-01-14

sigil approve

Approve a quarantined item, moving it from the quarantine directory to the approved directory. The package is then available for use.

bash

sigil approve <id>

# Example
sigil approve q_01a

sigil reject

Reject a quarantined item, permanently removing it from the quarantine directory. The package is deleted and never installed.

bash

sigil reject <id>

# Example
sigil reject q_03c

Account commands

sigil login

Authenticate with the Sigil cloud API. Required for Pro and Team features including cloud threat intelligence and the web dashboard.

bash

# Interactive login (opens browser)
sigil login

# Non-interactive login (for CI/CD)
sigil login --email user@example.com --password

Flag	Description
--email	Email address for non-interactive login
--password	Prompt for password on stdin (never passed as argument)

sigil logout

Clear the stored authentication token. Reverts the CLI to open-source mode.

bash

sigil logout

Scan phases

Every scan runs six analysis phases. Each phase has a weight multiplier that determines how much findings contribute to the total risk score.

#	Phase	Weight	What it scans
1	Install Hooks	10x	setup.py cmdclass, npm postinstall, Makefile targets
2	Code Patterns	5x	eval(), exec(), pickle.loads, child_process, subprocess shell=True
3	Network / Exfil	3x	requests.post, fetch(), axios, WebSockets, ngrok, Discord/Telegram webhooks
4	Credentials	2x	os.environ, .aws/credentials, SSH keys, API key patterns
5	Obfuscation	5x	base64.b64decode, atob(), String.fromCharCode, hex escapes
6	Provenance	1-3x	Git history depth, binary files, hidden dotfiles, large files
7	Prompt Injection	5x	Hidden instructions in comments, docstrings, markdown, and config files targeting AI agents
8	AI Skill Security	10x	Malicious AI skills, MCP servers, suspicious permissions, and publisher reputation signals

Supplementary checks

In addition to the eight core phases, Sigil integrates with external scanners when available on your system:

•semgrep — advanced multi-language pattern matching
•bandit — Python-specific security linting
•trufflehog — deep secret detection across git history
•safety — Python CVE scanning
•npm audit — JS dependency vulnerability scanning
•Dependency analysis — transitive dependency tree inspection
•Permission / scope analysis — file system and network permission checks

Verdicts and scoring

Each scan produces a numeric risk score and a corresponding verdict. The score is the weighted sum of all findings across the six phases.

Score	Verdict	Meaning	Recommended action
0–9	LOW RISK	No known malicious patterns detected	Auto-approve eligible
10–24	MEDIUM RISK	Multiple findings	Manual review
25–49	HIGH RISK	Significant suspicious patterns	Do not approve without thorough review
50+	CRITICAL RISK	Multiple strong indicators of malicious intent	Reject and report

Exit codes

Exit codes map directly to verdict severity, making it straightforward to gate CI/CD pipelines on scan results.

Code	Meaning
0	LOW RISK — score 0–9, or command completed successfully
1	CRITICAL RISK — score 50+, or command error
2	HIGH — score 25–49
3	MEDIUM — score 10–24
4	LOW — score 1–9

CI/CD usage

Use the exit code to gate deployments. Exit codes 1 and 2 indicate high-severity findings that should block a pipeline.

bash

# Block on HIGH or CRITICAL findings
sigil scan ./project
if [ $? -ge 2 ]; then echo "High-risk findings"; exit 1; fi

Environment variables

Override default paths and behavior with environment variables. Useful for CI/CD pipelines and custom directory structures.

Variable	Default	Description
SIGIL_QUARANTINE_DIR	~/.sigil/quarantine	Quarantine directory
SIGIL_APPROVED_DIR	~/.sigil/approved	Approved packages directory
SIGIL_LOG_DIR	~/.sigil/logs	Scan logs directory
SIGIL_REPORT_DIR	~/.sigil/reports	Scan reports directory
SIGIL_CONFIG	~/.sigil/config	Config file path
SIGIL_TOKEN	~/.sigil/token	Authentication token path
SIGIL_API_URL	https://api.sigil.nomark.dev	Cloud API URL

File types scanned

Sigil scans the following file extensions by default. Files outside this list are ignored during analysis.

.py.js.mjs.ts.tsx.jsx.sh.yaml.yml.json.toml

External scanner integration

Sigil automatically detects and integrates with these external scanners when they are available on your system. Install any of them to enrich your scan results.

Scanner	Install	Description
semgrep	pip install semgrep	Advanced multi-language pattern matching
bandit	pip install bandit	Python-specific security linting
trufflehog	brew install trufflehog	Deep secret detection across git history
safety	pip install safety	Python CVE scanning
npm audit	Bundled with npm	JS dependency vulnerability scanning

Optional, not required

External scanners are optional. Sigil's eight core phases run without any external dependencies. External scanners add depth to the analysis but are not required for a complete scan.

Previous← Quick Start NextAPI Reference →

Need help?

Ask a question in GitHub Discussions or check the troubleshooting guide.

Community Troubleshooting