Commands

Commands provide access to some of the more advanced features in lnav, like filtering and “search tables”. You can activate the command prompt by pressing the : key. At the prompt, you can start typing in the desired command and/or double-tap TAB to activate auto-completion and show the available commands. To guide you in the usage of the commands, a help window will appear above the command prompt with an explanation of the command and its parameters (if it has any). For example, the screenshot below shows the help for the :open command:

_images/open-help.png

Screenshot of the online help for the :open command.

In addition to online help, many commands provide a preview of the effects that the command will have. This preview will activate shortly after you have finished typing, but before you have pressed Enter to execute the command. For example, the :open command will show a preview of the first few lines of the file given as its argument:

_images/open-preview.png

Screenshot of the preview shown for the :open command.

The :filter-out pattern command is another instance where the preview behavior can help you craft the correct command-line. This command takes a PCRE regular expression that specifies the log messages that should be filtered out of the view. The preview for this command will highlight the portion of the log messages that match the expression in red. Thus, you can be certain that the regular expression is matching the log messages you are interested in before committing the filter. The following screenshot shows an example of this preview behavior for the string “launchd”:

_images/filter-out-preview.png

Screenshot showing the preview for the :filter-out launchd command.

Any errors detected during preview will be shown in the status bar right above the command prompt. For example, an attempt to open an unknown file will show an error message in the status bar, like so:

_images/open-error.png

Screenshot of the error shown when trying to open a non-existent file.

Tip

Note that almost all commands support TAB-completion for their arguments. So, if you are in doubt as to what to type for an argument, you can double- tap the TAB key to get suggestions. For example, the TAB-completion for the filter-in command will suggest words that are currently displayed in the view.

Note

The following commands can be disabled by setting the LNAVSECURE environment variable before executing the lnav binary:

  • :open

  • :pipe-to

  • :pipe-line-to

  • :write-*-to

This makes it easier to run lnav in restricted environments without the risk of privilege escalation.

Reference

:adjust-log-time timestamp

Change the timestamps of the top file to be relative to the given date

Parameters
  • timestamp* — The new timestamp for the top line in the view

Examples

To set the top timestamp to a given date:

:adjust-log-time 2017-01-02T05:33:00

To set the top timestamp back an hour:

:adjust-log-time -1h

:alt-msg msg

Display a message in the alternate command position

Parameters
  • msg* — The message to display

Examples

To display ‘Press t to switch to the text view’ on the bottom right:

:alt-msg Press t to switch to the text view
See Also

:echo msg, :eval command, :redirect-to [path], :write-csv-to path, :write-json-to path, :write-jsonlines-to path, :write-raw-to path, :write-screen-to path, :write-table-to path, :write-to path


:append-to path

Append marked lines in the current view to the given file

Parameters
  • path* — The path to the file to append to

Examples

To append marked lines to the file /tmp/interesting-lines.txt:

:append-to /tmp/interesting-lines.txt
See Also

:echo msg, :pipe-line-to shell-cmd, :pipe-to shell-cmd, :redirect-to [path], :write-csv-to path, :write-json-to path, :write-jsonlines-to path, :write-raw-to path, :write-screen-to path, :write-table-to path, :write-to path


:clear-comment

Clear the comment attached to the top log line

See Also

:comment text, :tag tag


:clear-highlight pattern

Remove a previously set highlight regular expression

Parameters
  • pattern* — The regular expression previously used with :highlight

Examples

To clear the highlight with the pattern ‘foobar’:

:clear-highlight foobar
See Also

:enable-word-wrap, :hide-fields field-name, :highlight pattern


:clear-partition

Clear the partition the top line is a part of


:close

Close the top file in the view


:comment text

Attach a comment to the top log line

Parameters
  • text* — The comment text

Examples

To add the comment ‘This is where it all went wrong’ to the top line:

:comment This is where it all went wrong
See Also

:clear-comment, :tag tag


:config option [value]

Read or write a configuration option

Parameters
  • option* — The path to the option to read or write

  • value — The value to write. If not given, the current value is returned

Examples

To read the configuration of the ‘/ui/clock-format’ option:

:config /ui/clock-format

To set the ‘/ui/dim-text’ option to ‘false’:

:config /ui/dim-text false
See Also

:reset-config option


:create-logline-table table-name

Create an SQL table using the top line of the log view as a template

Parameters
  • table-name* — The name for the new table

Examples

To create a logline-style table named ‘task_durations’:

:create-logline-table task_durations
See Also

:create-search-table table-name [pattern], :create-search-table table-name [pattern], :write-csv-to path, :write-json-to path, :write-jsonlines-to path, :write-raw-to path, :write-screen-to path, :write-table-to path


:create-search-table table-name [pattern]

Create an SQL table based on a regex search

Parameters
  • table-name* — The name of the table to create

  • pattern — The regular expression used to capture the table columns. If not given, the current search pattern is used.

Examples

To create a table named ‘task_durations’ that matches log messages with the pattern ‘duration=(?<duration>d+)’:

:create-search-table task_durations duration=(?<duration>\d+)
See Also

:create-logline-table table-name, :create-logline-table table-name, :delete-search-table table-name, :delete-search-table table-name, :write-csv-to path, :write-json-to path, :write-jsonlines-to path, :write-raw-to path, :write-screen-to path, :write-table-to path


:current-time

Print the current time in human-readable form and seconds since the epoch


:delete-filter pattern

Delete the filter created with :filter-in or :filter-out

Parameters
  • pattern* — The regular expression to match

Examples

To delete the filter with the pattern ‘last message repeated’:

:delete-filter last message repeated
See Also

:filter-in pattern, :filter-out pattern, :hide-lines-after date, :hide-lines-before date, :hide-unmarked-lines, :toggle-filtering


:delete-logline-table table-name

Delete a table created with create-logline-table

Parameters
  • table-name* — The name of the table to delete

Examples

To delete the logline-style table named ‘task_durations’:

:delete-logline-table task_durations
See Also

:create-logline-table table-name, :create-logline-table table-name, :create-search-table table-name [pattern], :create-search-table table-name [pattern], :write-csv-to path, :write-json-to path, :write-jsonlines-to path, :write-raw-to path, :write-screen-to path, :write-table-to path


:delete-search-table table-name

Create an SQL table based on a regex search

Parameters
  • table-name* — The name of the table to create

Examples

To delete the search table named ‘task_durations’:

:delete-search-table task_durations
See Also

:create-logline-table table-name, :create-logline-table table-name, :create-search-table table-name [pattern], :create-search-table table-name [pattern], :write-csv-to path, :write-json-to path, :write-jsonlines-to path, :write-raw-to path, :write-screen-to path, :write-table-to path


:delete-tags tag

Remove the given tags from all log lines

Parameters
  • tag — The tags to delete

Examples

To remove the tags ‘#BUG123’ and ‘#needs-review’ from all log lines:

:delete-tags #BUG123 #needs-review
See Also

:comment text, :tag tag


:disable-filter pattern

Disable a filter created with filter-in/filter-out

Parameters
  • pattern* — The regular expression used in the filter command

Examples

To disable the filter with the pattern ‘last message repeated’:

:disable-filter last message repeated
See Also

:enable-filter pattern, :filter-in pattern, :filter-out pattern, :hide-lines-after date, :hide-lines-before date, :hide-unmarked-lines, :toggle-filtering


:disable-word-wrap

Disable word-wrapping for the current view

See Also

:enable-word-wrap, :hide-fields field-name, :highlight pattern


:echo msg

Echo the given message to the screen or, if :redirect-to has been called, to output file specified in the redirect. Variable substitution is performed on the message. Use a backslash to escape any special characters, like ‘$’

Parameters
  • msg* — The message to display

Examples

To output ‘Hello, World!’:

:echo Hello, World!
See Also

:alt-msg msg, :append-to path, :eval command, :pipe-line-to shell-cmd, :pipe-to shell-cmd, :redirect-to [path], :redirect-to [path], :write-csv-to path, :write-csv-to path, :write-json-to path, :write-json-to path, :write-jsonlines-to path, :write-jsonlines-to path, :write-raw-to path, :write-raw-to path, :write-screen-to path, :write-screen-to path, :write-table-to path, :write-table-to path, :write-to path, :write-to path


:enable-filter pattern

Enable a previously created and disabled filter

Parameters
  • pattern* — The regular expression used in the filter command

Examples

To enable the disabled filter with the pattern ‘last message repeated’:

:enable-filter last message repeated
See Also

:filter-in pattern, :filter-out pattern, :hide-lines-after date, :hide-lines-before date, :hide-unmarked-lines, :toggle-filtering


:enable-word-wrap

Enable word-wrapping for the current view

See Also

:disable-word-wrap, :hide-fields field-name, :highlight pattern


:eval command

Evaluate the given command/query after doing environment variable substitution

Parameters
  • command* — The command or query to perform substitution on.

Examples

To substitute the table name from a variable:

:eval ;SELECT * FROM ${table}
See Also

:alt-msg msg, :echo msg, :redirect-to [path], :write-csv-to path, :write-json-to path, :write-jsonlines-to path, :write-raw-to path, :write-screen-to path, :write-table-to path, :write-to path


:filter-expr expr

Set the filter expression

Parameters
  • expr* — The SQL expression to evaluate for each log message. The message values can be accessed using column names prefixed with a colon

Examples

To set a filter expression that matched syslog messages from ‘syslogd’:

:filter-expr :log_procname = 'syslogd'

To set a filter expression that matches log messages where ‘id’ is followed by a number and contains the string ‘foo’:

:filter-expr :log_body REGEXP 'id\d+' AND :log_body REGEXP 'foo'
See Also

:clear-filter-expr, :filter-in pattern, :filter-out pattern, :hide-lines-after date, :hide-lines-before date, :hide-unmarked-lines, :toggle-filtering


:filter-in pattern

Only show lines that match the given regular expression in the current view

Parameters
  • pattern* — The regular expression to match

Examples

To filter out log messages that do not have the string ‘dhclient’:

:filter-in dhclient
See Also

:delete-filter pattern, :disable-filter pattern, :filter-out pattern, :hide-lines-after date, :hide-lines-before date, :hide-unmarked-lines, :toggle-filtering


:filter-out pattern

Remove lines that match the given regular expression in the current view

Parameters
  • pattern* — The regular expression to match

Examples

To filter out log messages that contain the string ‘last message repeated’:

:filter-out last message repeated
See Also

:delete-filter pattern, :disable-filter pattern, :filter-in pattern, :hide-lines-after date, :hide-lines-before date, :hide-unmarked-lines, :toggle-filtering


:goto line#|N%|date

Go to the given location in the top view

Parameters
  • line#|N%|date* — A line number, percent into the file, or a timestamp

Examples

To go to line 22:

:goto 22

To go to the line 75% of the way into the view:

:goto 75%

To go to the first message on the first day of 2017:

:goto 2017-01-01
See Also

:next-location, :next-mark type, :prev-location, :prev-mark type, :relative-goto line-count|N%


:help

Open the help text view


:hide-fields field-name

Hide log message fields by replacing them with an ellipsis

Parameters
  • field-name — The name of the field to hide in the format for the top log line. A qualified name can be used where the field name is prefixed by the format name and a dot to hide any field.

Examples

To hide the log_procname fields in all formats:

:hide-fields log_procname

To hide only the log_procname field in the syslog format:

:hide-fields syslog_log.log_procname
See Also

:enable-word-wrap, :highlight pattern, :show-fields field-name


:hide-file path

Hide the given file(s) and skip indexing until it is shown again. If no path is given, the current file in the view is hidden

Parameters
  • path — A path or glob pattern that specifies the files to hide


:hide-lines-after date

Hide lines that come after the given date

Parameters
  • date* — An absolute or relative date

Examples

To hide the lines after the top line in the view:

:hide-lines-after here

To hide the lines after 6 AM today:

:hide-lines-after 6am
See Also

:filter-in pattern, :filter-out pattern, :hide-lines-before date, :hide-unmarked-lines, :show-lines-before-and-after, :toggle-filtering


:hide-lines-before date

Hide lines that come before the given date

Parameters
  • date* — An absolute or relative date

Examples

To hide the lines before the top line in the view:

:hide-lines-before here

To hide the log messages before 6 AM today:

:hide-lines-before 6am
See Also

:filter-in pattern, :filter-out pattern, :hide-lines-after date, :hide-unmarked-lines, :show-lines-before-and-after, :toggle-filtering


:highlight pattern

Add coloring to log messages fragments that match the given regular expression

Parameters
  • pattern* — The regular expression to match

Examples

To highlight numbers with three or more digits:

:highlight \d{3,}
See Also

:clear-highlight pattern, :enable-word-wrap, :hide-fields field-name


:load-session

Load the latest session state


:mark

Toggle the bookmark state for the top line in the current view

See Also

:hide-unmarked-lines, :next-mark type, :prev-mark type


:next-location

Move to the next position in the location history

See Also

:goto line#|N%|date, :next-mark type, :prev-location, :prev-mark type, :relative-goto line-count|N%


:next-mark type

Move to the next bookmark of the given type in the current view

Parameters
  • type* — The type of bookmark – error, warning, search, user, file, meta

Examples

To go to the next error:

:next-mark error
See Also

:goto line#|N%|date, :hide-unmarked-lines, :mark, :next-location, :prev-location, :prev-mark type, :prev-mark type, :relative-goto line-count|N%


:open path

Open the given file(s) or URLs in lnav

Parameters
  • path — The path to the file to open

Examples

To open the file ‘/path/to/file’:

:open /path/to/file

:partition-name name

Mark the top line in the log view as the start of a new partition with the given name

Parameters
  • name* — The name for the new partition

Examples

To mark the top line as the start of the partition named ‘boot #1’:

:partition-name boot #1

:pipe-line-to shell-cmd

Pipe the top line to the given shell command

Parameters
  • shell-cmd* — The shell command-line to execute

Examples

To write the top line to ‘sed’ for processing:

:pipe-line-to sed -e 's/foo/bar/g'
See Also

:append-to path, :echo msg, :pipe-to shell-cmd, :redirect-to [path], :write-csv-to path, :write-json-to path, :write-jsonlines-to path, :write-raw-to path, :write-screen-to path, :write-table-to path, :write-to path


:pipe-to shell-cmd

Pipe the marked lines to the given shell command

Parameters
  • shell-cmd* — The shell command-line to execute

Examples

To write marked lines to ‘sed’ for processing:

:pipe-to sed -e s/foo/bar/g
See Also

:append-to path, :echo msg, :pipe-line-to shell-cmd, :redirect-to [path], :write-csv-to path, :write-json-to path, :write-jsonlines-to path, :write-raw-to path, :write-screen-to path, :write-table-to path, :write-to path


:prev-location

Move to the previous position in the location history

See Also

:goto line#|N%|date, :next-location, :next-mark type, :prev-mark type, :relative-goto line-count|N%


:prev-mark type

Move to the previous bookmark of the given type in the current view

Parameters
  • type* — The type of bookmark – error, warning, search, user, file, meta

Examples

To go to the previous error:

:prev-mark error
See Also

:goto line#|N%|date, :hide-unmarked-lines, :mark, :next-location, :next-mark type, :next-mark type, :prev-location, :relative-goto line-count|N%


:prompt type [–alt] [prompt] [initial-value]

Open the given prompt

Parameters
  • type* — The type of prompt – command, script, search, sql, user

  • –alt — Perform the alternate action for this prompt by default

  • prompt — The prompt to display

  • initial-value — The initial value to fill in for the prompt

Examples

To open the command prompt with ‘filter-in’ already filled in:

:prompt command : 'filter-in '

To ask the user a question:

:prompt user 'Are you sure? '

:pt-max-time

(null)


:pt-min-time

(null)


:quit

Quit lnav


:redirect-to [path]

Redirect the output of commands that write to stdout to the given file

Parameters
  • path — The path to the file to write. If not specified, the current redirect will be cleared

Examples

To write the output of lnav commands to the file /tmp/script-output.txt:

:redirect-to /tmp/script-output.txt
See Also

:alt-msg msg, :append-to path, :echo msg, :echo msg, :eval command, :pipe-line-to shell-cmd, :pipe-to shell-cmd, :write-csv-to path, :write-csv-to path, :write-json-to path, :write-json-to path, :write-jsonlines-to path, :write-jsonlines-to path, :write-raw-to path, :write-raw-to path, :write-screen-to path, :write-screen-to path, :write-table-to path, :write-table-to path, :write-to path, :write-to path


:redraw

Do a full redraw of the screen


:relative-goto line-count|N%

Move the current view up or down by the given amount

Parameters
  • line-count|N%* — The amount to move the view by.

Examples

To move 22 lines down in the view:

:relative-goto +22

To move 10 percent back in the view:

:relative-goto -10%
See Also

:goto line#|N%|date, :next-location, :next-mark type, :prev-location, :prev-mark type


:reset-config option

Reset the configuration option to its default value

Parameters
  • option* — The path to the option to reset

Examples

To reset the ‘/ui/clock-format’ option back to the builtin default:

:reset-config /ui/clock-format
See Also

:config option [value]


:reset-session

Reset the session state, clearing all filters, highlights, and bookmarks


:save-session

Save the current state as a session


:session lnav-command

Add the given command to the session file (~/.lnav/session)

Parameters
  • lnav-command* — The lnav command to save.

Examples

To add the command ‘:highlight foobar’ to the session file:

:session :highlight foobar

:set-min-log-level log-level

Set the minimum log level to display in the log view

Parameters
  • log-level* — The new minimum log level

Examples

To set the minimum log level displayed to error:

:set-min-log-level error

:show-fields field-name

Show log message fields that were previously hidden

Parameters
  • field-name — The name of the field to show

Examples

To show all the log_procname fields in all formats:

:show-fields log_procname
See Also

:enable-word-wrap, :hide-fields field-name, :highlight pattern


:show-file path

Show the given file(s) and resume indexing.

Parameters
  • path — The path or glob pattern that specifies the files to show


:show-lines-before-and-after

Show lines that were hidden by the ‘hide-lines’ commands

See Also

:filter-in pattern, :filter-out pattern, :hide-lines-after date, :hide-lines-before date, :hide-unmarked-lines, :toggle-filtering


:spectrogram field-name

Visualize the given message field using a spectrogram

Parameters
  • field-name* — The name of the numeric field to visualize.

Examples

To visualize the sc_bytes field in the access_log format:

:spectrogram sc_bytes

:summarize column-name

Execute a SQL query that computes the characteristics of the values in the given column

Parameters
  • column-name* — The name of the column to analyze.

Examples

To get a summary of the sc_bytes column in the access_log table:

:summarize sc_bytes

:switch-to-view view-name

Switch to the given view

Parameters
  • view-name* — The name of the view to switch to.

Examples

To switch to the ‘schema’ view:

:switch-to-view schema

:tag tag

Attach tags to the top log line

Parameters
  • tag — The tags to attach

Examples

To add the tags ‘#BUG123’ and ‘#needs-review’ to the top line:

:tag #BUG123 #needs-review
See Also

:comment text, :delete-tags tag, :untag tag


:toggle-filtering


:toggle-view view-name

Switch to the given view or, if it is already displayed, switch to the previous view

Parameters
  • view-name* — The name of the view to toggle the display of.

Examples

To switch to the ‘schema’ view if it is not displayed or switch back to the previous view:

:toggle-view schema

:unix-time seconds

Convert epoch time to a human-readable form

Parameters
  • seconds* — The epoch timestamp to convert

Examples

To convert the epoch time 1490191111:

:unix-time 1490191111

:untag tag

Detach tags from the top log line

Parameters
  • tag — The tags to detach

Examples

To remove the tags ‘#BUG123’ and ‘#needs-review’ from the top line:

:untag #BUG123 #needs-review
See Also

:comment text, :tag tag


:write-to path

Overwrite the given file with any marked lines in the current view

Parameters
  • path* — The path to the file to write

Examples

To write marked lines to the file /tmp/interesting-lines.txt:

:write-to /tmp/interesting-lines.txt
See Also

:alt-msg msg, :append-to path, :echo msg, :echo msg, :eval command, :pipe-line-to shell-cmd, :pipe-to shell-cmd, :redirect-to [path], :redirect-to [path], :write-csv-to path, :write-csv-to path, :write-json-to path, :write-json-to path, :write-jsonlines-to path, :write-jsonlines-to path, :write-raw-to path, :write-raw-to path, :write-screen-to path, :write-screen-to path, :write-table-to path, :write-table-to path


:zoom-to zoom-level

Zoom the histogram view to the given level

Parameters
  • zoom-level* — The zoom level

Examples

To set the zoom level to ‘1-week’:

:zoom-to 1-week