Superagent LogoSuperagent

CLI

Command-line interface for interacting with Superagent

Sign up at https://app.superagnet.sh to obtain an API Key

Command-line tool for validating prompts and commands with the Superagent endpoint.

Installation

Terminal
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:

Terminal
superagent guard "Write a Python function to calculate fibonacci numbers"

Output:

Output
Prompt approved by Superagent

Test a malicious command

Terminal
superagent guard "Delete all files in the system with rm -rf /"

Output:

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:

Terminal
echo '{"prompt": "Generate a friendly greeting"}' | superagent guard

Configuration

Environment variables

Set your API key using an environment variable:

Terminal
export SUPERAGENT_API_KEY="sa_your_key_here"
superagent guard "Your prompt here"

Alternatively, configure it in your shell profile (~/.bashrc, ~/.zshrc, etc.):

Terminal
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:

Terminal
export SUPERAGENT_API_BASE_URL="https://your-custom-endpoint.com/api/guard"

Commands

guard

Validates a prompt or command against Superagent Guard policies.

Syntax:

Terminal
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 approved
  • 1 - Prompt blocked
  • 2 - Error occurred (API failure, configuration issue, etc.)

Examples:

Terminal
# 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:

Terminal
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 successful
  • 2 - Error occurred (API failure, configuration issue, etc.)

Examples:

Terminal
# 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:

Response
{
  "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.

Terminal
# 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:

Response
{
  "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.

Terminal
# 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:

Response
{
  "rejected": false,
  "decision": {
    "status": "pass"
  },
  "reasoning": "Document appears safe with no security threats detected"
}

Or if threats are detected:

Response
{
  "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, and usage 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:

Terminal
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 successful
  • 2 - Error occurred (API failure, configuration issue, etc.)

Examples:

Terminal
# 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:

Response
{
  "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 and content fields, and optionally a url 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:

Response
{
  "decision": "pass"
}

Blocked:

Response
{
  "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

FieldTypeDescription
decision"pass" | "block"Machine verdict that determines whether the prompt is allowed.
reasonstringHuman-readable explanation for blocked prompts.
hookSpecificOutputobjectAdditional metadata for integration with external tools.

Error handling

Missing API key

Error:

Error
L ERROR: SUPERAGENT_API_KEY not set

Solution: Set the environment variable:

Terminal
export SUPERAGENT_API_KEY="sa_your_key_here"

Invalid JSON (stdin mode)

Error:

Error
L ERROR: Failed to parse JSON from stdin

Solution: Ensure you're sending valid JSON with a prompt field:

Terminal
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:

validate.sh
#!/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
# .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:

.git/hooks/pre-commit
#!/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:

Terminal
superagent: command not found

Solution: Ensure npm's global bin directory is in your PATH:

Terminal
npm config get prefix
# Add the bin directory to your PATH
export PATH="$(npm config get prefix)/bin:$PATH"

Permission denied

Issue:

Error
EACCES: permission denied

Solution: Install without sudo using npm's prefix:

Terminal
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
npm install -g @superagent-ai/cli

Resources