Run commands in the CLI

Cortex XSOAR enables you to run system commands, integration commands, scripts, and more, from an integrated CLI.

Cortex XSOAR enables you to run system commands, integration commands, and scripts from an integrated command line interface (CLI), which enables you to make comments in your incident (in plain text or Markdown) and to execute automation scripts, system commands, and integration commands. This gives SOC teams the power to execute automations ad-hoc to support their investigations or make notes as they investigate incidents.

Note

If you are unable to run commands in the CLI, you may not have sufficient user role permissions. Contact your Cortex XSOAR administrator for more details.

In the CLI, you can run various commands, by typing the following:

Action	Description
!	Runs integration commands, scripts, and built-in commands, such as adding evidence and assigning an analyst.
/	Runs system commands and operations, such as adding notes and closing an investigation.
@	Sends notifications to administrators, teams, and analysts by tagging users.

You can find relevant commands, scripts, and arguments with the CLI’s auto-complete feature. This also includes fuzzy searching to help you find relevant commands based on keywords. If you type the exclamation mark (!) and start typing, autocomplete populates with options that might suit your needs. For example, if you want to work with tasks, type !task, and all commands and scripts that include the task in their name will display.

The CLI is available throughout Cortex XSOAR, except Marketplace and while editing Playbooks.

Tip

You can use the up/down arrow buttons in the CLI to do a reverse history search for previous commands with the same prefix.

You can hide the CLI when it is not needed by clicking on the down arrow to the right of the CLI. You can click the same button to restore the CLI. If you can't see the ^ button, remove the ? Help Center button. To restore the Help Center, click Help (left menu) and click In-App Help Center.

Note

The CLI is not available in the Main Account in a multi-tenant deployment. You can run commands from the Main Account.

Using special characters

Characters	Description
`&&,
\, \n, \t, \r, ", ^, :, comma, and space	To use these characters, place them within single or double quotes and use an escape character \.

Tip

When writing a query or complex text in the CLI, we strongly recommend enclosing your text with the backtick (`) character. Text within the backticks does not require you to escape single quotation marks ('), double quotation marks (''), or backslashes (\).

Common arguments

The following common arguments are available for every script run from the CLI.

Argument Name	Description
auto-extract	Whether/when to extract indicators. Possible values: inline: Extracts indicators within the indicator extraction run context (synchronously). outofBand: Extracts indicators in parallel (asynchronously) to other actions. none: Does not extract indicators (recommended for scripts with large outputs when indicator extraction is not required).
execution-password	Supplies a password to run a password-protected script.
execution-timeout	Defines how long a command waits in seconds before it times out.
extend-context	Select which information from the raw JSON you want to add to the context data. For a single value: contextKey=RawJsonOutputPath For multiple values: contextKey1=RawJsonOutputPath1::contextKey2=RawJsonOutputPath2
ignore-outputs	Possible values: true or false. If set to true, it does not store outputs in the context (besides extend context).
raw-response	Possible values: true or false. If set to true, it returns the raw JSON result from the script.
retry-count	Determines how many times the script attempts to run before generating an error.
retry-interval	Determines the wait time (in seconds) between each script execution.
using	Selects which integration instance runs the command.
using-brand	Selects which integration runs the command. If the selected integration has multiple instances, the script may run multiple times. Use the using argument to select a single integration instance.
using-category	Selects which category of integrations runs the command. If the selected category includes multiple integration instances, the script may run multiple times. Use the using argument to select a single integration instance.

Run commands in the Automations browser

You can view and run commands and scripts (not system commands, operations, and notifications) in the Automations Browser, by clicking next to the CLI.

The Automations Browser enables you to run commands and all associated arguments. The scripts and commands are separated into sections such as scripts and built-in commands. In each argument, you can do the following:

• Hardcode the value
• Use a dynamic value

  You can dynamically pass information into the argument, by clicking the curly bracket. For example, the EmailAskUser command asks a user a question via email. In the email argument, rather than typing the user's email address, you can send it to whoever created the incident.

  1. In the email field, click the curly brackets.
  2. In the search box, enter created.
  3. Under INCIDENT DETAILS click Created by.

     The email argument appears as ${incident.dbotCreatedBy}.
  4. Run the command.

     An email is sent to the user who created the incident.

  You can use transformers and filters to filter and transform data from the command. For more information, see Filter and transform data.

Common arguments

Argument	Description
Using	Selects which integration instance runs the command.
Extend context	Determines the wait time (in seconds) between each script execution. For a single value: contextKey=RawJsonOutputPath For multiple values: contextKey1=RawJsonOutputPath1::contextKey2=RawJsonOutputPath2
Ignore outputs	Does not store outputs in the context (besides extend context).
Execution timeout (seconds)	Defines how long a command waits in seconds before it times out.
Number of retries	Determines how many times the script attempts to run before generating an error.
Retry interval (seconds)	Determines the wait time (in seconds) between each script execution.

Examples using the CLI

To run the print script with a value of "hello" and the key a from the context:

!Print value="hello ${a}"

To run the searchIncidentv2 script with the query of myfield equals "this is a test" using escape characters:

!SearchIncidentsV2 query="myfield:\"this is a test\""

To run the same query using backticks:

!SearchIncidentsV2 query=`myfield:"this is a test"`

To run the Python command returning Hello World using escape characters:

!py script="demisto.results(\"hello world\")"

To run the Python command returning Hello World using backticks:

!py script=`demisto.results("hello world")`