Syntax for searches in the CLI

If you use Splunk Enterprise, you can issue search commands from the command line using the Splunk CLI. This is a quick discussion of the syntax and options available for using the search and rtsearch commands in the CLI.

The syntax for CLI searches is similar to the syntax for searches you run from Splunk Web except that you can pass parameters outside of the search object to control the time limit of the search, specify the server where the search is to be run, and specify how results are displayed.

search | rtsearch [object][-parameter <value>]

Search defaults

By default when you run a search from the CLI, the search is uses All Time as the time range. You can specify time ranges using one of the CLI search parameters, such as earliest_time, index_earliest, or latest_time.

The first 100 events are returned when you run a historical search using the CLI. Use the maxout search parameter to specify the number of events to return.

Search objects

Search objects are enclosed in single quotes (' ') and can be keywords, expressions, or a series of search commands. On Windows OS use double quotes (" ") to enclose your search object.

• For more information about searching, see Start searching in the Search Tutorial.
• For a brief description of every search command, see the Command quick reference in the Search Reference.
• For a quick reference for Splunk concepts, features, search commands, and functions, see the Quick Reference Guide in the Search Reference.

Search objects can include not only keywords and search commands but also fields and modifiers to specify the events you want to retrieve and the results you want to generate.

• For more information about fields, see Use fields to search in the Search Tutorial.
• For more information about default fields and how to use them, see Use default and internal fields in the Knowledge Manager Manual.
• For more information about time modifiers, see Time modifiers for search in the Search Reference.

Search parameters

Search parameters are options that control the way the search is run or the way the search results are displayed. All of these parameters are optional. Parameters that take Boolean values support 0, false, f, no as negatives and 1, true, t, yes as positives.

Specify these search parameters at the end of your search, after you have specified all of the commands and command arguments. See Example 4.

Parameter	Values	Defaults	Description
app	<app_name>	search	Specify the name of the app in which to run your search.
batch	<bool>	F	Indicates how to handle updates in preview mode.
detach	<bool>	F	Triggers an asynchronous search and displays the job ID and TTL for the search.
earliest_time	<time-modifier>	−	The relative time modifier for the start time of the search. This is optional for search and required for rtsearch.
header	<bool>	T	Indicates whether to display a header in the table output mode.
index_earliest	<time-modifer>		The start time of the search. This can be expressed as an epoch or relative time modifier and uses the same syntax as the "earliest" and "latest" time modifiers for search language. This is optional for both search and rtsearch.
index_latest	<time-modifer>		The end time of the search. This can be expressed as an epoch or relative time modifier and uses the same syntax as the "earliest" and "latest" time modifiers for search language. This is optional for both search and rtsearch.
latest_time	<time-modifer>	−	The relative time modifer for the end time of search. For search, if this is not specified, it defaults to the end of the time (or the time of the last event in the data), so that any "future" events are also included. For rtsearch, this is a required parameter and the real-time search will not run if it's not specified.
max_time	<number>	0	The length of time in seconds that a search job runs before it is finalized. A value of 0 means that there is no time limit.
maxout	<number>	search, 100 rtsearch, 0	The maximum number of events to return or send to stdout when exporting events. A value of 0 means that it will output an unlimited number of events.
output	rawdata, table, csv, auto	Use rawdata for non-transforming searches. Use table for transforming searches.	Indicates how to display the job.
preview	<bool>	T	Indicates that reporting searches should be previewed (displayed as results are calculated).
timeout	<number>	0	The length of time in seconds that a search job is allowed to live after running. A value of 0 means that the job is canceled immediately after it is run.
uri	[http|https]://name_of_server:management_port		Specify the server name and management port. name_of_server can be the fully-resolved domain name or the IP address of the Splunk server. The default uri value is the mgmtHostPort value that you defined in the Splunk server's web.conf. For more information, see Access and use the CLI on a remote Splunk Server in the Admin manual.
wrap	<bool>	T	Indicates whether to line wrap for individual lines that are longer than the terminal width.

Examples

You can see more examples in the CLI help information.

1. Retrieve events from yesterday that match root sessions

./splunk search "session root daysago=1"

2. Retrieve events that match web access errors and detach the search

./splunk search 'eventtype=webaccess error' -detach true

3. Run a windowed real-time search

./splunk rtsearch 'index=_internal' -earliest_time 'rt-30s' -latest_time 'rt+30s'

See more examples of Real-time searches and reports in the CLI in the Admin Manual.

4. Return a list of unique hostnames

There are two recommended ways that you can do this. This first is with the stats command:

./splunk search 'index=* | stats count by host | fields - count' -preview true

Alternatively, since you are only interested in the host field, you can use the metadata command:

./splunk search '| metadata type=hosts | fields host' -preview true

Here, the -preview flag is optional and used to view the results as it is returned. In contrast, the table command, unlike the fields command, generally requires all inputs before it can emit any non-preview output. In this case, you would need to use the preview flag to be able to view the results of the search.

5. Return yesterday's internal events

./splunk search 'index=_internal' -index_earliest -1d@d -index_latest @d