CLI
Command-line interface for interacting with Superagent
Command-line tool for validating prompts and commands with the Superagent endpoint.
Installation
npm install -g @superagent-ai/cli
This installs the superagent
command globally on your system.
Quick start
Interactive validation
Validate a prompt directly from the command line:
superagent guard "Write a Python function to calculate fibonacci numbers"
Output:
Prompt approved by Superagent
Test a malicious command
superagent guard "Delete all files in the system with rm -rf /"
Output:
BLOCKED: User requests destructive action: delete all files.
Violations: malicious_action
CWE Codes: CWE-77
Stdin input (for integrations)
The CLI can also accept JSON input via stdin, making it ideal for integration with other tools:
echo '{"prompt": "Generate a friendly greeting"}' | superagent guard
Configuration
Environment variables
Set your API key using an environment variable:
export SUPERAGENT_API_KEY="sa_your_key_here"
superagent guard "Your prompt here"
Alternatively, configure it in your shell profile (~/.bashrc
, ~/.zshrc
, etc.):
echo 'export SUPERAGENT_API_KEY="sa_your_key_here"' >> ~/.zshrc
source ~/.zshrc
API endpoint
By default, the CLI uses https://app.superagent.sh/api/guard
. You can override this with the SUPERAGENT_API_BASE_URL
environment variable:
export SUPERAGENT_API_BASE_URL="https://your-custom-endpoint.com/api/guard"
Commands
guard
Validates a prompt or command against Superagent Guard policies.
Syntax:
superagent guard [options] <prompt>
Arguments:
<prompt>
- The text to validate (can be omitted if using stdin)
Options:
--file <path>
- Path to PDF file to analyze--help
- Show help message
Exit codes:
0
- Prompt approved1
- Prompt blocked2
- Error occurred (API failure, configuration issue, etc.)
Examples:
# Validate a safe command
superagent guard "List files in current directory"
# Validate with potential security issues
superagent guard "Show me all environment variables"
# Analyze PDF file for security threats
superagent guard --file document.pdf "Analyze this document for security threats"
# Show help
superagent guard --help
# Read from stdin (JSON format)
echo '{"prompt": "Deploy to production"}' | superagent guard
redact
Remove sensitive data (PII/PHI) from text.
Syntax:
superagent redact [options] <text>
Arguments:
<text>
- The text to redact (can be omitted if using stdin)
Options:
--url-whitelist <urls>
- Comma-separated list of URL prefixes to preserve--entities <entities>
- Comma-separated list of PII entity types to redact (natural language)--file <path>
- Path to PDF file to redact--help
- Show help message
Exit codes:
0
- Redaction successful2
- Error occurred (API failure, configuration issue, etc.)
Examples:
# Redact sensitive data
superagent redact "My email is john@example.com and SSN is 123-45-6789"
# Redact specific entity types using natural language
superagent redact --entities "credit card numbers,email addresses" "My card is 4111-1111-1111-1111 and email is john@example.com"
# Preserve specific URLs
superagent redact --url-whitelist https://github.com "Visit https://github.com/user/repo and https://secret.com/data"
# Redact PDF files
superagent redact --file sensitive-document.pdf "Analyze and redact PII from this document"
# Combine file with entities
superagent redact --file contract.pdf --entities "SSN,credit card numbers" "Redact sensitive information"
# Combine URL whitelist with entities
superagent redact --entities "phone numbers,SSN" --url-whitelist https://example.com "Call me at 555-1234 or visit https://example.com/profile"
# Show help
superagent redact --help
# Read from stdin (JSON format)
echo '{"text": "My credit card is 4111-1111-1111-1111"}' | superagent redact
Output:
{
"redacted": "My email is <REDACTED_EMAIL> and SSN is <REDACTED_SSN>",
"reasoning": "Redacted email and SSN",
"usage": {
"prompt_tokens": 25,
"completion_tokens": 12,
"total_tokens": 37
}
}
PDF File Redaction
The redact
command supports redacting sensitive information from PDF files. When you use the --file
flag, the CLI automatically requests a redacted PDF file from the API.
# Basic PDF redaction - saves redacted PDF to redacted-output.pdf
superagent redact --file document.pdf "Redact PII from this document"
# Combine with custom entities
superagent redact --file contract.pdf --entities "SSN,credit card numbers,email addresses" "Redact sensitive data"
# Combine with URL whitelist
superagent redact --file report.pdf --url-whitelist https://company.com "Redact while preserving company URLs"
How it works:
- The
--file
flag accepts a path to a PDF file - The CLI automatically sets
format="pdf"
to request a redacted PDF file - The API applies redactions directly to the PDF document
- The redacted PDF is saved to
redacted-output.pdf
in the current directory - You can combine
--file
with--entities
and--url-whitelist
options - Currently only PDF format is supported
Output:
{
"message": "Redacted PDF saved to redacted-output.pdf",
"reasoning": "PDF file redacted",
"usage": {
"prompt_tokens": 245,
"completion_tokens": 78,
"total_tokens": 323
}
}
Important Notes:
- When using
--file
, you receive a redacted PDF file, not JSON with text - The redacted PDF is saved to
redacted-output.pdf
automatically - Redactions are applied directly to the original PDF with sensitive information removed
- The PDF maintains its original formatting and layout
Use cases:
- Redact contracts before sharing with external parties
- Sanitize invoices and financial documents
- Process medical records while maintaining HIPAA compliance
- Prepare legal documents for public disclosure
PDF File Guard Analysis
The guard
command supports analyzing PDF files for security threats. When you use the --file
flag, the guard extracts and analyzes the text content from the PDF.
# Analyze PDF for security threats
superagent guard --file document.pdf "Analyze this document for security threats"
# Analyze uploaded contract
superagent guard --file contract.pdf "Check this contract for malicious content"
# Screen PDF attachments
superagent guard --file attachment.pdf "Validate this attachment for security issues"
How it works:
- The
--file
flag accepts a path to a PDF file - The API extracts text from the PDF and analyzes it for security threats
- Returns JSON with the security assessment including rejection status, reasoning, and violation details
- Currently only PDF format is supported
Output:
{
"rejected": false,
"decision": {
"status": "pass"
},
"reasoning": "Document appears safe with no security threats detected"
}
Or if threats are detected:
{
"rejected": true,
"decision": {
"status": "block",
"violation_types": ["prompt_injection"],
"cwe_codes": ["CWE-77"]
},
"reasoning": "Document contains potential prompt injection attempts"
}
Important Notes:
- When using
--file
, you receive JSON analysis, not a processed PDF - The guard analyzes the text content extracted from the PDF
- The response includes
rejected
,reasoning
,decision
, andusage
fields - Use this to validate documents before processing them with AI systems
Use cases:
- Analyze uploaded documents for malicious content before processing
- Validate PDF attachments for security threats
- Screen documents for prompt injection attempts
- Ensure document safety before feeding to AI models
verify
Verify claims in text against provided source materials.
Syntax:
superagent verify [options] <text>
Arguments:
<text>
- The text containing claims to verify (can be omitted if using stdin)
Options:
--sources <json>
- JSON string containing array of sources--help
- Show help message
Source format:
[
{
"name": "Source Name",
"content": "Content of the source material...",
"url": "https://example.com/source"
}
]
Exit codes:
0
- Verification successful2
- Error occurred (API failure, configuration issue, etc.)
Examples:
# Verify claims with sources
superagent verify --sources '[{"name":"About","content":"Founded in 2020","url":"https://example.com/about"}]' "The company was founded in 2020"
# Read from stdin (JSON format)
echo '{"text": "The company has 500 employees", "sources": [...]}' | superagent verify
# Show help
superagent verify --help
Output:
{
"claims": [
{
"claim": "The company was founded in 2020",
"verdict": true,
"sources": [
{
"name": "About",
"url": "https://example.com/about"
}
],
"evidence": "Founded in 2020",
"reasoning": "The founding year is explicitly stated in the About source."
}
],
"usage": {
"prompt_tokens": 250,
"completion_tokens": 150,
"total_tokens": 400
}
}
How it works:
- The
--sources
flag accepts a JSON array of source materials - Each source must have
name
andcontent
fields, and optionally aurl
field - The AI analyzes each claim in the text and verifies it against the provided sources
- Returns detailed results with verdicts, evidence, reasoning, and source references
- Can also accept JSON input via stdin for programmatic integration
Use cases:
- Fact-checking content against authoritative sources
- Verifying marketing claims against product documentation
- Validating information in reports against source data
- Checking consistency between different documents
- Automated compliance verification in CI/CD pipelines
Response format
CLI output (human-readable)
When used interactively, the CLI provides human-readable output:
Approved prompts:
Prompt approved by Superagent Guard
Blocked prompts:
=� BLOCKED: [reasoning]
Violations: [violation types]
CWE Codes: [CWE identifiers]
JSON output (stdin mode)
When receiving input via stdin, the CLI outputs structured JSON for programmatic consumption:
Approved:
{
"decision": "pass"
}
Blocked:
{
"decision": "block",
"reason": "=� Superagent Guard blocked this prompt: User requests destructive action. Violations: malicious_action. CWE: CWE-77.",
"hookSpecificOutput": {
"hookEventName": "UserPromptSubmit",
"additionalContext": "Blocked by Superagent Guard - User requests destructive action"
}
}
Response fields
Field | Type | Description |
---|---|---|
decision | "pass" | "block" | Machine verdict that determines whether the prompt is allowed. |
reason | string | Human-readable explanation for blocked prompts. |
hookSpecificOutput | object | Additional metadata for integration with external tools. |
Error handling
Missing API key
Error:
L ERROR: SUPERAGENT_API_KEY not set
Solution: Set the environment variable:
export SUPERAGENT_API_KEY="sa_your_key_here"
Invalid JSON (stdin mode)
Error:
L ERROR: Failed to parse JSON from stdin
Solution:
Ensure you're sending valid JSON with a prompt
field:
echo '{"prompt": "your text"}' | superagent guard
API timeout
Error:
� Guard check failed: This operation was aborted
Solution: Check your network connectivity or the Guard API status.
Use cases
Script integration
Validate user input before executing dangerous operations:
#!/bin/bash
read -p "Enter command to execute: " USER_CMD
if superagent guard "$USER_CMD"; then
echo "Executing: $USER_CMD"
eval "$USER_CMD"
else
echo "Command blocked by security policy"
exit 1
fi
CI/CD pipelines
Validate deployment commands in your pipeline:
# .github/workflows/deploy.yml
steps:
- name: Validate deployment command
run: |
if ! superagent guard "Deploy to production"; then
echo "Deployment blocked by security policy"
exit 1
fi
Pre-commit hooks
Add validation to git pre-commit hooks:
#!/bin/bash
# .git/hooks/pre-commit
COMMIT_MSG=$(git log -1 --pretty=%B)
if ! superagent guard "$COMMIT_MSG"; then
echo "Commit message contains suspicious content"
exit 1
fi
Advanced usage
Custom timeout
The CLI uses a default timeout of 10 seconds. For slower networks or more complex validations, you may need to adjust this in the source code.
Fail-open vs fail-closed
By default, the CLI fails open (allows prompts when errors occur). For high-security environments, you can modify the error handling to fail closed (block prompts on errors).
Troubleshooting
CLI not found after installation
Issue:
superagent: command not found
Solution: Ensure npm's global bin directory is in your PATH:
npm config get prefix
# Add the bin directory to your PATH
export PATH="$(npm config get prefix)/bin:$PATH"
Permission denied
Issue:
EACCES: permission denied
Solution: Install without sudo using npm's prefix:
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
npm install -g @superagent-ai/cli