---
title: "CLI Quickstart Guide"
slug: "silent-push-command-line-interface-cli-guide"
updated: 2026-04-24T14:38:44Z
published: 2026-04-24T14:38:44Z
canonical: "help.silentpush.com/silent-push-command-line-interface-cli-guide"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.silentpush.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Quickstart Guide

The Silent Push CLI is a powerful tool that allows you to interact directly with the Silent Push API from your terminal. It supports scoring, enriching, and querying DNS records for indicators of compromise (IOCs), such as domains and IP addresses. This guide covers installation, basic usage, advanced features, scripting, and development extensions.

## Requirements

- Python 3.9 or later with pip
- Windows users only: Microsoft Build Tools for Visual C++

## Installation

```plaintext
python3 -m pip install SilentPushCLI
```

### Linux & macOS

```plaintext
export SILENT_PUSH_API_KEY=YOUR-API-KEY
```

### Windows

```plaintext
setx /m SILENT_PUSH_API_KEY YOUR-API-KEY
```

Restart your Command Prompt after setting the key.

*Demo video:* [Silent Push CLI Interface](https://youtu.be/d4WApEZcXFg)

## Usage

The CLI follows this syntax:

```plaintext
sp COMMAND [SUB-COMMAND...] IOC [PARAMETER=VALUE...] [OPTION...]
```

Get help:

```plaintext
sp help -v
sp padns query a --help
```

### Examples

Score a single domain:

```plaintext
sp score ig.com
```

Enrich a domain with explanations:

```plaintext
sp enrich ig.com -es
```

Bulk enrich multiple domains:

```plaintext
sp bulk_enrich ig.com x.com ibm.com -es
```

Query DNS records:

```plaintext
sp padns query a ig.com limit=2 sort=last_seen/-
```

## Supported Commands and Sub-commands

The CLI currently supports the following commands and sub-commands:

### Core Commands

These are the top-level commands you can run directly.

| Command | Description |
| --- | --- |
| `score` | Calculate risk scores for one or more Indicators of Compromise (IOCs). |
| `enrich` | Enrich a single IOC with additional threat intelligence data. |
| `bulk_enrich` | Enrich multiple IOCs in a single batch operation (ideal for large lists). |
| `padns` | Enter the Passive DNS query context to access PADNS sub-commands (see below). |
| `feedsearch` |  |
| `websearch` |  |
| `threatcheck` |  |
| `bulk_threatcheck` |  |
| `spql` (multiple queries) |  |
| `load` | Load a command context (e.g., `load padns` to switch to PADNS mode). |
| `unload` | Unload the current command context and return to the main level. |

### PADNS Sub-commands

After entering PADNS mode (`padns` or `load padns`), use these sub-commands to build precise Passive DNS queries.

### Query Types

Specify the DNS record type you want to search for.

| Sub-command | Description |
| --- | --- |
| `query` | General DNS query (any available record type). |
| `any` | Query any record type. |
| `anyipv4` | Query records associated with IPv4 addresses. |
| `anyipv6` | Query records associated with IPv6 addresses. |
| `a` | Query A records (IPv4 addresses). |
| `aaaa` | Query AAAA records (IPv6 addresses). |
| `cname` | Query CNAME records (canonical names). |
| `mx` | Query MX records (mail exchangers). |
| `ns` | Query NS records (name servers). |
| `ptr4` | Query PTR records for IPv4 (reverse lookups). |
| `ptr6` | Query PTR records for IPv6 (reverse lookups). |
| `soa` | Query SOA records (Start of Authority). |
| `txt` | Query TXT records (text data, often SPF/DKIM). |

#### Answer Types

Focus on specific answer content returned in DNS records.

| Sub-command | Description |
| --- | --- |
| `answer` | Reverse lookup for any answer values. |
| `a` | A record answers (IPv4). |
| `aaaa` | AAAA record answers (IPv6). |
| `cname` | CNAME record answers. |
| `mx` | MX record answers. |
| `mxhash` | Hashed MX record answers (useful for clustering). |
| `ns` | NS record answers. |
| `nshash` | Hashed NS record answers. |
| `ptr4` | PTR4 record answers. |
| `ptr6` | PTR6 record answers. |
| `soa` | SOA record answers. |
| `soahash` | Hashed SOA record answers. |
| `txt` | TXT record answers. |
| `txthash` | Hashed TXT record answers. |

## Quick Tips

- Use `load padns` to enter PADNS mode and access all sub-commands without prefixing.
- Chain sub-commands for precise queries (e.g., `padns a answer` for A record reverse lookups).
- Type `help` or `help [command]` in the CLI for usage examples and available options.

## Options

Options can be applied to most commands to customize the output.

### Global options (all commands)

- `-j, --json`: Output in JSON format (default).
- `-c, --csv`: Output in CSV format.
- `-t, --tsv`: Output in TSV format.
- `-h, --help`: Display help for the command.

## Enrich/Bulk Enrich specific options

- `-e, --explain`: Include details on data used for score calculations.
- `-s, --scan_data`: Include Host scanning data details.

### Interactive Mode

Launch the interactive console by running `sp` without arguments. This enters the `sp` console, where you can execute commands without the `sp` prefix.

### Example session

```plaintext
SP# score ig.com
SP# padna query a ig.com limit=1
```

## Load and Unload Commands

Use `load` to switch to a specific command context, loading its sub-commands for easier access. `unload` returns to the base console.

### Example: Loading PADNS Context

```python
SP# load padns
PADNS loaded
SP (PADNS)# query ns ig.com limit=1
SP (PADNS)# unload padns        
```

You can still run base commands (e.g., `score`) while in a loaded context.

## SPQL Commands (Multiline)

```plaintext
SP# websearch 'domain="ibm.com"
  AND scan_date > "2025-01-01"' limit=2 -tv;
```

## Scripting

The CLI supports scripting for project automation.

### run_pyscript Command

Execute a Python script that interacts with the CLI. Example script `my_script.py`):

```plaintext
# my_script.py
        result = app('score ibm.com -t')
        print(result.data)
```

Run it with:

```plaintext
sp run_pyscript my_script.py
```

### run_script Command

Run a text file with CLI commands (one per line). Example file `my_script.txt`):

```python
# my_script.txt
        padns query mx ig.com limit=2
        score ig.com -c
```

Execute with:

```plaintext
sp run_script my_script.txt
```

Alternatively, redirect input:

```plaintext
sp < my_script.txt
```

### Batch Execution Tips

Leverage shell scripting for efficient bulk operations. For example, enrich domains from a file:

```plaintext
cat to_enrich.txt | xargs sp bulk_enrich
```

> [!NOTE]
> Note: Keep IOC types consistent in the file (e.g., all domains or all IPs) to avoid errors.

## For Developers

### Using the Library

Integrate the CLI as a Python library in your code.

```python
from sp.main import main as sp
sp(['enrich ig.com])
from sp.main import App
from sp.common.utils import AppFileManager
app = App(application_manager=AppFileManager('my app'))
app.onecmd_plus_hooks('enrich ig.com')
print(app.last_result)      
```

### Extend the Commands – Guidelines

Commands are defined in the `sp/commands` directory. The project uses the CMD2 library. To add a new command:

- Create a new Python file in `sp/commands/` (e.g., `my_new_command.py`).
- Follow this template:

```python
@with_default_category("My New Category")
        class MyNewCommandSet(BaseCommandSet):
        my_new_parser = BaseCommandSet._get_arg_parser()
        my_new_parser.add_argument("-s", "--some_argument")

        @with_argparser(my_new_parser)
        def do_something(self, params: Statement):
        with self.MyNewCommand(params, self) as my_new_command:
        my_new_command.something()

        class MyNewCommand(BaseCommand):

        def __enter__(self):
        # Pre-execution setup
        super().__enter__()
        return self

        def something(self):
        # Core logic
        self._response = {"result": "your command result"}

        def __exit__(self, exc_type, exc_val, exc_tb):
        # Post-execution cleanup
        super().__exit__(exc_type, exc_val, exc_tb)
```

- Import it in `sp/commands/__init__.py`:

```python
# After existing imports
        from .my_new_command import *
```

- Add it to initial commands in `sp/settings.py`:

```python
def get_initial_commands():
        from sp.commands import (
        # Other imports
        MyNewCommandSet
        )
        return {
        # Other commands
        MyNewCommandSet(),
        }
```

Test your command:

```plaintext
sp your_command --help
```

Contact [jorgeley@silentpush.com](mailto:jorgeley@silentpush.com) for assistance.

The system, device, or server identified by an indicator (e.g., IP address, domain, or hostname) within Silent Push’s threat intelligence, associated with potential malicious activity or infrastructure.