CLI Reference¶
The soarapps command-line tool is the main interface for working with Splunk SOAR apps from the command line. It provides commands for creating, building, and managing apps.
soarapps¶
Usage: soarapps [OPTIONS] COMMAND [ARGS]...
A command-line tool for helping with SOAR Apps development
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy │
│ it or customize the installation. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ version Display the version of the SOAR SDK. │
│ manifests │
│ package │
│ init Initialize a new SOAR app. │
│ convert Convert a SOAR connector to a SOAR SDK app. │
│ test Run unit and integration tests │
╰──────────────────────────────────────────────────────────────────────────────╯
version¶
Usage: soarapps version [OPTIONS]
Display the version of the SOAR SDK.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
manifests¶
Usage: soarapps manifests [OPTIONS] COMMAND [ARGS]...
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ display Parse and print the contents of a manifest JSON file. │
│ create Create a manifest file from the given project context. │
│ create-notice Generate a NOTICE file with third-party license │
│ attributions. │
╰──────────────────────────────────────────────────────────────────────────────╯
display¶
Usage: soarapps manifests display [OPTIONS] FILENAME
Parse and print the contents of a manifest JSON file.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * filename TEXT [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
create¶
Usage: soarapps manifests create [OPTIONS] FILENAME PROJECT_CONTEXT
Create a manifest file from the given project context.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * filename TEXT [required] │
│ * project_context TEXT [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
create-notice¶
Usage: soarapps manifests create-notice [OPTIONS] [PROJECT_CONTEXT]
Generate a NOTICE file with third-party license attributions.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ project_context [PROJECT_CONTEXT] Path to the SOAR app project │
│ directory. │
│ [default: (current directory)] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --output-file -o PATH Output path for the NOTICE file. │
│ [default: (<project_context>/NOTICE)] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
package¶
Usage: soarapps package [OPTIONS] COMMAND [ARGS]...
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ build Build a SOAR app package in TGZ format. │
│ install Install the app tgz to the specified Splunk SOAR system. │
╰──────────────────────────────────────────────────────────────────────────────╯
build¶
Usage: soarapps package build [OPTIONS] [PROJECT_CONTEXT]
Build a SOAR app package in TGZ format.
Args:
project_context: Path to the app project directory
output_file: Path where the app TGZ should be created
with_sdk_wheel_from: Optional path in which to find a wheel for this SDK
Options:
--output-file, -o: Path where the packaged app will be saved
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ project_context [PROJECT_CONTEXT] [default: (current working │
│ directory)] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --output-file -o PATH [default: (derived from │
│ pyproject.toml)] │
│ --with-sdk-wheel-from -w PATH Optional path to an SDK wheel to │
│ include │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
install¶
Usage: soarapps package install [OPTIONS] APP_TARBALL SOAR_INSTANCE
Install the app tgz to the specified Splunk SOAR system.
..note:
Authentication can be provided in several ways:
- Set the PH_AUTH_TOKEN environment variable to use token-based auth
(recommended for CI/CD and SAML-only instances).
- Set the PHANTOM_USERNAME and PHANTOM_PASSWORD environment variables for
password-based auth.
- Otherwise, you will be prompted for username and password interactively.
The SOAR instance can also be set via the SOAR_INSTANCE environment variable.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * app_tarball PATH [required] │
│ * soar_instance TEXT [env var: SOAR_INSTANCE] [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --username TEXT [env var: PHANTOM_USERNAME] │
│ --force --no-force [default: no-force] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
init¶
Usage: soarapps init [OPTIONS] COMMAND [ARGS]...
Initialize a new SOAR app.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --name TEXT Name of the app to │
│ initialize. │
│ --description TEXT Description of the │
│ app to initialize. │
│ --authors TEXT [default: <class │
│ 'list'>] │
│ --python-version -p [3.13|3.14] Supported Python │
│ versions for the │
│ app. │
│ [default: <bound │
│ method │
│ PythonVersion.all │
│ of <enum │
│ 'PythonVersion'>>] │
│ --dependencies TEXT [default: <class │
│ 'list'>] │
│ --appid UUID [default: │
│ (dynamic)] │
│ --app-dir DIRECTORY Directory in which │
│ to initialize the │
│ SDK app. │
│ [default: (current │
│ directory/<app │
│ name>)] │
│ --copyright TEXT [default: │
│ Copyright (c) │
│ {year} Splunk │
│ Inc.] │
│ --version TEXT [default: 1.0.0] │
│ --type TEXT [default: generic] │
│ --vendor TEXT [default: Splunk │
│ Inc.] │
│ --publisher TEXT [default: Splunk │
│ Inc.] │
│ --uv-index TEXT URL of a custom │
│ Python Package │
│ Index your app │
│ should use when │
│ downloading │
│ dependencies. Apps │
│ distributed on │
│ Splunkbase should │
│ not change this │
│ setting. │
│ [default: │
│ https://pypi.pyth… │
│ --product TEXT │
│ --fips-compliant --no-fips-compli… [default: │
│ no-fips-compliant] │
│ --encrypt-cache-s… --no-encrypt-cac… Encrypt │
│ asset.cache_state │
│ at rest. │
│ [default: │
│ encrypt-cache-sta… │
│ --encrypt-ingest-… --no-encrypt-ing… Encrypt │
│ asset.ingest_state │
│ at rest. │
│ [default: │
│ encrypt-ingest-st… │
│ --overwrite --no-overwrite [default: │
│ no-overwrite] │
│ --private --public Generate │
│ pre-commit config │
│ for a private app │
│ by omitting │
│ Splunkbase-only │
│ static tests. │
│ [default: public] │
│ --non-interactive Disable the guided │
│ wizard and require │
│ all needed options │
│ to be provided. │
│ --help Show this message │
│ and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
convert¶
Usage: soarapps convert [OPTIONS] APP_DIR [OUTPUT_DIR] COMMAND [ARGS]...
Convert a SOAR connector to a SOAR SDK app.
This command will convert a SOAR connector directory into a SOAR SDK app
directory.
The connector directory should contain the necessary files and structure for
conversion.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * app_dir DIRECTORY [required] │
│ output_dir [OUTPUT_DIR] Directory to output the converted SDK │
│ app. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --overwrite --no-overwrite [default: no-overwrite] │
│ --uv-index TEXT [default: │
│ https://pypi.python.org/simple] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
test¶
Usage: soarapps test [OPTIONS] COMMAND [ARGS]...
Run unit and integration tests
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ unit Run unit tests. │
│ integration Run integration tests against a SOAR instance. │
╰──────────────────────────────────────────────────────────────────────────────╯
unit¶
Usage: soarapps test unit [OPTIONS]
Run unit tests.
This command runs the unit test suite, excluding integration tests.
By default, tests run in parallel for faster execution.
Examples:
# Run all unit tests in parallel
soarapps test unit
# Run unit tests with coverage
soarapps test unit --coverage
# Run specific test file
soarapps test unit -t tests/test_decorators.py
# Run without parallelism
soarapps test unit --no-parallel
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --parallel -p --no-parallel Run tests in parallel using │
│ pytest-xdist │
│ [default: parallel] │
│ --coverage -c Run with coverage reporting │
│ --verbose -v Verbose test output │
│ --test-path -t PATH Path to specific test file or │
│ directory │
│ --junit-xml PATH Path to save JUnit XML test results │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
integration¶
Usage: soarapps test integration [OPTIONS] INSTANCE_IP
Run integration tests against a SOAR instance.
This command runs the integration test suite against a specified SOAR
instance.
Tests run similar to the GitHub CI workflow.
Examples:
# Run integration tests against a specific instance
soarapps test integration 10.1.19.88 -u admin -p password
# Run tests with automation broker
soarapps test integration 10.1.19.88 --automation-broker my-broker
# Run specific test file
soarapps test integration 10.1.19.88 -t
tests/integration/test_example_app.py
# Save test results to file
soarapps test integration 10.1.19.88 --junit-xml results.xml
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * instance_ip TEXT SOAR instance IP address or hostname [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --username -u TEXT SOAR instance username │
│ [env var: PHANTOM_USERNAME] │
│ --password -p TEXT SOAR instance password │
│ [env var: PHANTOM_PASSWORD] │
│ --retries -r INTEGER Number of test retries on │
│ failure │
│ [default: 2] │
│ --automation-broker -ab TEXT Automation broker name for │
│ on-prem tests │
│ [env var: │
│ AUTOMATION_BROKER_NAME] │
│ --force-automation-broker Force use of automation broker │
│ for all tests │
│ [env var: │
│ FORCE_AUTOMATION_BROKER] │
│ --verbose -v Verbose test output │
│ --test-path -t PATH Path to specific test file or │
│ directory │
│ --junit-xml PATH Path to save JUnit XML test │
│ results │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
App CLI¶
The App class automatically generates a command-line interface (CLI) for your app. This CLI can be used to run actions (and verify their behavior) from the command line.
$ python src/app.py --help
usage: app.py [-h] [--soar-url SOAR_URL] [--soar-user SOAR_USER] [--soar-password SOAR_PASSWORD] {action,webhook} ...
positional arguments:
{action,webhook}
action Run an action
webhook Invoke a webhook handler
options:
-h, --help show this help message and exit
--soar-url SOAR_URL SOAR URL to connect to. Can be provided via PHANTOM_BASE_URL environment variable as well.
--soar-user SOAR_USER
Username to connect to SOAR instance. Can be provided via PHANTOM_USER environment variable as well
--soar-password SOAR_PASSWORD
Password to connect to SOAR instance. Can be provided via PHANTOM_PASSWORD environment variable as well
You can run any action defined in your app by using the action command. For example:
$ python src/app.py action my-action --help
usage: app.py action my-action [-h] -p PARAMS_FILE -a ASSET_FILE
optional arguments:
-h, --help show this help message and exit
-p PARAMS_FILE, --params-file PARAMS_FILE
JSON file containing action parameters
-a ASSET_FILE, --asset-file ASSET_FILE
JSON file containing asset configuration