CLI Usage

Run Sheath from the command line with the sheath:lint Artisan command.

#Basic Usage

Run Sheath without a path to lint the directories from your configuration. You can also pass a directory, file, or glob pattern:

php artisan sheath:lint
php artisan sheath:lint resources/views
php artisan sheath:lint resources/views/components/button.blade.php
php artisan sheath:lint "resources/views/**/*.blade.php"

#Command Reference

The command options control configuration, reporting, fixes, file selection, and runtime behavior.

#Configuration and Output

Choose a config file, preset, and report format with these options.

Examples:

php artisan sheath:lint --config=sheath.custom.php
php artisan sheath:lint --preset=strict --preset=stylistic
php artisan sheath:lint --preset=migration --fix --dangerous
php artisan sheath:lint --print-config
php artisan sheath:lint --format=json
php artisan sheath:lint --format=checkstyle --output=sheath-report.xml

--preset replaces the config's preset value for the current command. Rules listed individually in the config still apply. Use --only when you want to run one rule without any others.

--print-config includes a ruleStatus section that shows which rules Sheath will run. See packageRequirementMode.

#Standard Output and Standard Error

Standard output contains only the report. Fix summaries, skipped items, the parallel progress bar, and the --stats summary go to standard error.

That separation keeps machine-readable reports parseable. Use --output when another tool should read the report from a file:

php artisan sheath:lint --format=json --output=sheath-report.json

#Previewing and Applying Fixes

Preview available fixes before changing files, or apply them directly.

Examples:

# apply safe fixes only
php artisan sheath:lint --fix

# preview safe fixes only
php artisan sheath:lint --dry-run

# preview safe and dangerous fixes
php artisan sheath:lint --dry-run --dangerous

# apply safe and dangerous fixes
php artisan sheath:lint --fix --dangerous

The fix options behave as follows:

• Sheath does not apply dangerous fixes unless you explicitly opt in.
• After each fix pass, Sheath lints the file again. It stops when no more fixes apply or after ten passes. A later pass can apply compatible fixes that become available after an earlier change.
• --dry-run calculates the same fixes as --fix but does not change any files.
• If you provide both --fix and --dry-run, Sheath uses dry-run mode. It does not change any files and writes a notice to standard error.
• --dangerous has no effect without --fix or --dry-run. Sheath writes a notice to standard error when you use this combination.
• --fix cannot be combined with --generate-baseline or --update-baseline. Apply fixes first, then generate a baseline from the remaining violations.

#Rule Selection and Overrides

Run a focused set of rules or change their severity for the current command.

Supported severities:

• error
• warning
• info
• off

Examples:

php artisan sheath:lint --rule=a11y-alt-text:error
php artisan sheath:lint --rule=security-csrf-field:warning --rule=seo-require-title:off
php artisan sheath:lint --only=a11y-alt-text,security-csrf-field
php artisan sheath:lint --only=blade-no-debug --rule=blade-no-debug:error

Unknown rule IDs in the config, --rule, or --only stop the command before linting starts. This prevents a typo from silently disabling a rule in continuous integration (CI). A malformed --rule value, such as one without a rule ID or severity, also stops the command and reports the problem.

A rule that --only names but the configuration does not mention runs at the rule's own default severity.

#Ignore Handling

Add path exclusions for the current command, or bypass all configured exclusions.

php artisan sheath:lint --ignore-pattern="resources/views/vendor/**"
php artisan sheath:lint --ignore-pattern="**/legacy/**" --ignore-pattern="**/generated/**"
php artisan sheath:lint --no-ignore

#Thresholds and Exit Behavior

Set warning and error thresholds to control when the command fails.

php artisan sheath:lint --max-warnings=0
php artisan sheath:lint --max-warnings=10

The value must be a non-negative integer, or -1 to disable the threshold. Invalid values such as --max-warnings=abc fail the run instead of being read as 0.

Sheath returns one of these exit codes:

Sheath returns exit code 1 in any of these cases:

• an error-severity violation was reported
• a parser error was reported
• warnings exceeded --max-warnings
• a file could not be read or written
• the provided paths matched no files
• invalid configuration, including an unknown rule ID in --rule, --only, or the config, a malformed --rule or --max-warnings value, conflicting flags (--fix --generate-baseline, --fix --update-baseline, --generate-baseline --update-baseline), an unknown --preset, or an unknown --format
• a cache, baseline, report, or parallel worker operation failed

#Result Caching

Cache results for unchanged files in the default or a custom location.

php artisan sheath:lint --cache
php artisan sheath:lint --cache --cache-location=storage/framework/cache/sheath-cache.json

Each cache entry depends on the source content, resolved configuration, active rules, parser configuration, installed packages, and Sheath version. Custom rules that depend on other files or runtime state must add those inputs to the cache context described in Custom Rules.

#Baseline

Create or apply a baseline when existing violations cannot be fixed immediately.

Examples:

php artisan sheath:lint --generate-baseline
php artisan sheath:lint --generate-baseline --baseline=build/sheath-baseline.json
php artisan sheath:lint --baseline=sheath-baseline.json
php artisan sheath:lint --update-baseline
php artisan sheath:lint --ignore-baseline

You cannot combine --generate-baseline with --update-baseline. You also cannot use --fix or --dry-run with either baseline operation. Apply fixes first, then create or update the baseline with the remaining violations.

#Laravel Shortcuts

Choose one or more of Laravel's conventional view directories.

php artisan sheath:lint --views
php artisan sheath:lint --components
php artisan sheath:lint --emails
php artisan sheath:lint --components --emails

An explicit path argument or shortcut takes priority over an ignore pattern that excludes the entire selected directory. For example, --emails lints resources/views/emails even though the default config ignores that directory. Patterns that exclude files or directories inside the selected path still apply.

#Standard Input

Pipe template source to Sheath when no input file is available.

echo '<img src="hero.jpg">' | php artisan sheath:lint --stdin
Get-Content resources/views/welcome.blade.php | php artisan sheath:lint --stdin --stdin-filename=welcome.blade.php

Adding --fix writes the fixed source to standard output instead of a report because there is no input file to change. The exit code still reflects any remaining findings. See Auto-fix.

Get-Content resources/views/welcome.blade.php | php artisan sheath:lint --stdin --fix

When you use --stdin, Sheath ignores path arguments and writes a notice to standard error.

Baseline filtering, generation, and update work with stdin when --stdin-filename identifies the buffer. Hashes are calculated from the piped source, including unsaved editor content.

Caching and parallelism operate on discovered files, so --cache, --parallel, and --processes have no effect with stdin. The same is true of --views, --components, --emails, --ignore-pattern, and --no-ignore. Sheath emits a notice on standard error when any of these combinations is used.

#PowerShell Input

Use -Raw so PowerShell sends the template as one string. If the resulting input starts with a UTF-8 byte order mark, Sheath removes it before linting:

Get-Content resources/views/welcome.blade.php -Raw | php artisan sheath:lint --stdin --stdin-filename=welcome.blade.php

PowerShell decodes the file and encodes the native-command stream according to the PowerShell version and session settings. Use an editor integration or another byte-preserving producer when exact malformed source bytes matter.

#Parallel Linting

Lint files across multiple worker processes when the optional runtime is available.

php artisan sheath:lint --parallel
php artisan sheath:lint --parallel --processes=4
php artisan sheath:lint --parallel --cache --stats

Parallel mode requires the optional runtime packages documented in Installation and works on Linux, macOS, and Windows. If the packages are missing, Sheath warns and falls back to sequential linting. Small runs may also stay sequential automatically. With explicit --parallel, invalid --processes values fail before the runtime availability fallback.

Use --parallel-if-available when sequential fallback should be silent. Use explicit --parallel when a missing runtime should produce a warning.

Options that depend on another option are ignored when used alone. Sheath prints a notice for --processes without --parallel, --cache-location without --cache, and --stdin-filename without --stdin.

#Inline Suppressions

Report suppressed findings by ignoring suppression comments in templates.

# Honour suppression comments (default)
php artisan sheath:lint

# Report everything, including suppressed findings
php artisan sheath:lint --no-inline-config

See Inline Suppressions for the comment syntax.

#Diagnostics

Add timing, cache, and package-rule statistics to standard error.

php artisan sheath:lint --stats
php artisan sheath:lint --parallel --cache --stats

When package-aware rules are skipped or disabled, stats include package rule counts.

#Parser Errors

If a file has parser errors, Sheath reports those diagnostics and skips rule checks for that file. Fix the syntax, then run the linter again to see any rule findings.

#Common Workflows

These examples combine options for common local and CI tasks.

#Local Cleanup

Apply available safe fixes, then preview any dangerous fixes that remain:

php artisan sheath:lint --fix
php artisan sheath:lint --dry-run --dangerous

#CI

Treat warnings as failures and format annotations for GitHub Actions:

php artisan sheath:lint --max-warnings=0 --format=github

Use the github reporter only in GitHub Actions. For other systems, preserve the normal exit status and choose a report schema the receiving tool explicitly accepts. See CI/CD Integration.

#Incremental Adoption on an Existing App

Create a baseline before fixing files so existing findings do not block adoption:

php artisan sheath:lint --generate-baseline
php artisan sheath:lint
php artisan sheath:lint --fix
php artisan sheath:lint --update-baseline

#See Also

• Configuration: available settings and presets
• Rules: built-in rule inventory
• Auto-fix: previewing and applying fixes
• Baseline: adopting Sheath with existing findings