Introduction to Swell CLI

Swell is Stairwell’s cross-platform command-line interface (CLI) for programmatically interacting with the Stairwell platform. Built in Go, it enables automation, data ingestion, querying, and operational workflows directly from your terminal.

Run the following command to view available options:

swell

Core Commands

Swell provides a set of primary commands for interacting with the platform:

• auth – Manage authentication
• completion – Generate shell completion scripts
• config – View current configuration
• foundation – Interact with foundation services
• objects – Work with files and objects
• onboard – Register a machine as an asset
• query – Query resources in your environment
• tags – Manage tags across entities
• verify – Run diagnostics and environment checks
• version – Display CLI version information
• yara – Manage YARA rules

For detailed usage of any command:

swell <command> --help

Getting Started

To use Swell, you’ll need:

1. An authentication token
2. An environment ID

Authentication

Authenticate with:

swell auth login

You will be prompted for your API key. Once authenticated, the token is stored locally and automatically used for future commands.

The auth command also supports:

• login – Authenticate the CLI
• logout – Remove stored credentials
• maintenance – Generate a maintenance token

Configuration

Swell uses a YAML configuration file located at:

~/.config/swell/swell.yaml

You can store commonly used values such as:

auth_token: YOUR_AUTH_TOKEN
environment_id: YOUR_ENVIRONMENT_ID

This eliminates the need to repeatedly pass global flags.

Uploading Files with Swell

Swell can be used to ingest files into the Stairwell platform for analysis.

Step 1: Onboard an Asset (Optional)

Register the current system as an asset:

swell onboard <ASSET_NAME> --environment_id <ENVIRONMENT_ID>

This returns an Asset ID, which is required for uploads.

The asset name is descriptive, but uploads require the Asset ID. If you skip onboarding, you can use your environment’s default asset.

Step 2: Upload Files

Upload files or directories using:

swell objects upload --asset=<ASSET_ID> <PATH>

Examples:

# Upload a directory
swell objects upload --asset=ID /data

# Upload an entire system
swell objects upload --asset=ID /

During ingestion:

• Files are hashed and analyzed
• Known files are deduplicated
• Unique files are uploaded
• File metadata (path, timestamps, hash) is recorded

Initial scans of large systems may be resource-intensive.

Working with YARA Rules

Swell provides full lifecycle management for YARA rules.

swell yara --help

Available operations:

• list – View rules
• upload – Add rules
• download – Retrieve rules
• delete – Remove rules

Listing Rules

Option 1: Pass environment ID explicitly

swell yara list --environment_id <ENVIRONMENT_ID>

Option 2: Use configuration

After setting environment_id in your config file:

swell yara list

Diagnostics with the verify Command

The verify command provides customer-side diagnostics to ensure your environment is correctly configured to communicate with the Stairwell platform.

swell verify --help

Available Subcommands

connectivity

Verifies that your system can reach Stairwell’s public endpoints:

swell verify connectivity

This check helps identify:

• Network reachability issues (e.g., firewall or proxy restrictions)
• TLS or certificate validation problems
• Misconfigured endpoint addresses

Use this command if requests are failing, timing out, or behaving inconsistently.

compatibility

Detects locally installed software that may interfere with Swell:

swell verify compatibility

This includes identifying:

• Endpoint protection or antivirus software
• Host-based firewalls
• Other security tools that may block file access or network communication

Use this command if:

• File ingestion is incomplete or slow
• Files are unexpectedly skipped
• Behavior differs across systems

When to Use verify

Run swell verify when:

• Setting up Swell for the first time
• Troubleshooting connectivity issues
• Investigating failed uploads or scans
• Validating a new environment or network configuration

Global Flags

The verify command supports standard global flags, including:

• --environment_id – Target environment
• --config_file – Custom configuration file
• --auth_token – Manually provide authentication
• --insecure – Disable TLS verification (not recommended)

Summary

Swell provides a flexible, scriptable interface to the Stairwell platform, enabling:

• Secure authentication
• Asset onboarding and tracking
• File ingestion and analysis
• Querying and tagging
• YARA rule management
• Environment diagnostics and troubleshooting

It is designed for both interactive use and integration into automated workflows.