Splunk® Enterprise

Search Reference

Download manual as PDF

Download topic as PDF

Syntax for searches in the 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 the "Start searching" topic 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.

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} positives.

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.

Example 1: Retrieve events from yesterday that match root sessions.

./splunk search "session root daysago=1"


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

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

Example 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.

Example 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.

Example 5: Return yesterday's internal events.

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

PREVIOUS
About searches in the CLI
 

This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.4.9, 6.4.10, 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 6.6.9, 6.6.10, 6.6.11, 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.2.0, 7.2.1


Comments

Example 3 above doesn't work in windows, even with "objects" and complains about invalid time for earliest_time

Lakshman238
March 11, 2016

-output json is not documented.

Wegscd
October 22, 2015

The example using the metadata command appears to be wrong:<br /><br />./splunk search '| metadata type=hosts | fields hosts' -preview true <br /><br />Should probably be:<br /><br />./splunk search '| metadata type=hosts | fields host' -preview true

Christian.cloutier
October 10, 2014

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters