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 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:


: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:


:clear-comment

Clear the comment attached to the top log line

See Also:


: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:


: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:


: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:


: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 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:


: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:


: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:


: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:


: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:


: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:


:disable-word-wrap

Disable word-wrapping for the current view

See Also:


:echo msg

Echo the given message

Parameters:

  • msg — The message to display

Examples:

To output ‘Hello, World!’:

:echo Hello, World!

See Also:


: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:


:enable-word-wrap

Enable word-wrapping for the current view

See Also:


:eval command

Evaluate the given command/query after doing environment variable substitution

Parameters:

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

Examples:

To output the user’s home directory:

:eval :echo $HOME

To substitute the table name from a variable:

:eval ;SELECT * FROM ${table}

See Also:


: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:


: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:


: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:


: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:


: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:


: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:


:hide-unmarked-lines


: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:


:load-session

Load the latest session state

:mark

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

See Also:


:next-location

Move to the next position in the location history

See Also:


: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:


:open path

Open the given file(s) 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:


: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:


:prev-location

Move to the previous position in the location history

See Also:


: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:


:quit

Quit lnav

:redirect-to path

Redirect the output of commands 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:


: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:


: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:


:reset-session

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

:save-config

Save the current configuration state

See Also:


: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:


:show-lines-before-and-after

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

See Also:


: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:


: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:


:write-screen-to path


: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:


: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