shellfirm check
Check a command without executing it
The check command evaluates a shell command against shellfirm's pattern database and returns the result without executing the command.
Usage
shellfirm check --command <COMMAND> [OPTIONS]Options
| Flag | Description | Default |
|---|---|---|
--command <CMD> | The command to check (required) | - |
--test | Exit code only: 0 = safe, 1 = risky. No interactive prompt. | false |
--json | Output a full JSON risk assessment | false |
Exit codes
| Code | Meaning |
|---|---|
0 | Command is safe (no patterns matched or all below threshold) |
1 | Command is risky (patterns matched at or above threshold) |
Examples
Interactive check
shellfirm check --command "rm -rf /"This runs the full check pipeline and presents a challenge if the command is risky.
Non-interactive test
Non-interactive Test
$ shellfirm check --command "rm -rf /" --test
$ echo $?
1
Returns only the exit code. Useful in scripts and CI pipelines.
JSON output
shellfirm check --command "git push --force origin main" --jsonOutput:
{
"allowed": false,
"risk_level": "Normal",
"severity": "High",
"matched_rules": [
{
"id": "git:force_push",
"description": "Force push can overwrite remote history.",
"severity": "High",
"group": "git"
}
],
"alternatives": [
{
"command": "git push --force-with-lease",
"explanation": "Prevents overwriting others' work",
"source": "regex-pattern"
}
],
"context": {
"risk_level": "Normal",
"labels": []
},
"requires_human_approval": false,
"denial_reason": "Severity HIGH meets or exceeds agent auto-deny threshold HIGH"
}Safe command
Safe Command Check
$ shellfirm check --command "echo hello" --test
$ echo $?
0
shellfirm check --command "echo hello" --json{
"allowed": true,
"risk_level": "Normal",
"severity": null,
"matched_rules": [],
"alternatives": [],
"context": {
"risk_level": "Normal",
"labels": []
},
"requires_human_approval": false
}CI/CD usage
Use --test for binary pass/fail checks in pipelines:
if ! shellfirm check --command "$DEPLOY_CMD" --test; then
echo "Command blocked by shellfirm"
exit 1
fiUse --json for detailed reporting:
RESULT=$(shellfirm check --command "$CMD" --json)
echo "$RESULT" | jq '.matched_rules[].description'