Cli

The S4E command-line interface lets you manage assets, scans, findings, actions, and playbooks directly from your terminal. It is built on top of the Python SDK and supports scripting, CI/CD pipelines, and interactive use.

Installation

pip install s4e-cli

Note

Python 3.9 or later is required. Installing s4e-cli also installs the s4e-sdk package as a dependency.

Configuration

Before running any command, configure your API credentials:

s4e config set --api-key YOUR_API_KEY --api-url https://api.s4e.io/v1

Credentials are stored in ~/.s4e/config.json. You can maintain multiple profiles:

s4e config set --profile staging --api-key STAGING_KEY --api-url https://staging.s4e.io/v1
s4e --profile staging assets list

Command Structure

Every command follows a consistent pattern:

s4e <resource> <action> [options]

Resources include assets, scan, findings, actions, and playbooks. Actions vary by resource but typically include list, create, get, delete, and export.

Common Commands

Assets

# List all assets
s4e assets list

# List assets with a filter
s4e assets list --type domain --status active

# Add a new asset
s4e assets add --domain example.com --tags production,web

# Get details for a specific asset
s4e assets get --id ast_01h8x

Scans

# Create and start a scan
s4e scan create --asset-id ast_01h8x --type full

# Check scan status
s4e scan status --id scn_03k9z

# List recent scans
s4e scan list --limit 10 --status completed

Findings

# List critical findings
s4e findings list --severity critical

# List findings for a specific asset
s4e findings list --asset-id ast_01h8x --severity high,critical

# Export findings to CSV
s4e findings export --format csv --output findings.csv

# Export findings to JSON
s4e findings export --format json --output findings.json

Actions and Playbooks

# Trigger a remediation action
s4e actions trigger --action-id act_firewall_block --target 203.0.113.50

# Run a playbook
s4e playbooks run --playbook-id pb_incident_response --params '{"severity":"critical"}'

# List available playbooks
s4e playbooks list

Output Formats

By default the CLI renders output as a human-readable table. Use the --format flag to change the output:

Format	Flag	Description
Table	`--format table`	Default. Aligned columns for terminal.
JSON	`--format json`	Machine-readable JSON.
CSV	`--format csv`	Comma-separated values.

s4e assets list --format json
s4e findings list --severity high --format csv

Tip

Use --format json when piping output to other tools or storing results for later processing.

Shell Completion

Enable tab completion for your shell:

# Bash
s4e completion bash >> ~/.bashrc

# Zsh
s4e completion zsh >> ~/.zshrc

# Fish
s4e completion fish > ~/.config/fish/completions/s4e.fish

After reloading your shell, press Tab to auto-complete resource names, actions, and flag names.

Environment Variables

The CLI reads the following environment variables. They take precedence over values in the config file:

Variable	Description
`S4E_API_KEY`	API key for authentication.
`S4E_API_URL`	Base URL of the S4E API.
`S4E_PROFILE`	Config profile name to use.
`S4E_FORMAT`	Default output format.

export S4E_API_KEY="sk_live_..."
export S4E_API_URL="https://api.s4e.io/v1"
s4e assets list

Warning

Avoid storing API keys in shell history. Use environment variables or a secrets manager in CI/CD pipelines instead of passing --api-key on the command line.

Scripting Examples

Pipe findings to jq

s4e findings list --severity critical --format json | jq '.[].title'

Export and upload to S3

s4e findings export --format csv --output /tmp/findings.csv
aws s3 cp /tmp/findings.csv s3://my-bucket/reports/findings-$(date +%F).csv

Loop over assets and trigger scans

for id in $(s4e assets list --format json | jq -r '.[].id'); do
    s4e scan create --asset-id "$id" --type quick
done

CI/CD gate - fail if critical findings exist

count=$(s4e findings list --severity critical --format json | jq 'length')
if [ "$count" -gt 0 ]; then
    echo "Blocking deployment: $count critical findings found."
    exit 1
fi

Tip

Combine --format json with jq for powerful filtering and transformation directly in shell scripts.