CLI

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

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:

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

CLI

Installation

Quick start

Interactive validation

Test a malicious command

Stdin input (for integrations)

Configuration

Environment variables

API endpoint

Commands

`guard`

`redact`

PDF File Redaction

PDF File Guard Analysis

`verify`

Response format

CLI output (human-readable)

JSON output (stdin mode)

Response fields

Error handling

Missing API key

Invalid JSON (stdin mode)

API timeout

Use cases

Script integration

CI/CD pipelines

Pre-commit hooks

Advanced usage

Custom timeout

Fail-open vs fail-closed

Troubleshooting

CLI not found after installation

Permission denied

Resources

On this page