Not clear from documentation how to use ":external-access", and what's supported

[dardhal]

lnav version
v0.13.2 is the latest

Describe the bug
My goal is, for some log analysis (given set of logs that has to be analyzed for a number of different things, but I don't necessarily know up-front which, or how many iterations will be necessary) to be done lowering the setting-up costs of the task.

So instead of running lnav scripts from the CLI to get the results, which incurs the loading up and indexing of the input files as many times as scripts I need to run (sometimes several scripts with different parameters), I would prefer loading up all the necessary input files, and repeatedly work on the indexed files, running as many scripts or commands as I want.

The ultimate goal is to leverage lnav as a short of resident log parsing, processing and analysis service, to be called from some AI-based agent, getting results mostly (but not ony) from SQL (in CSV or JSON format), so that the AI-based agent can avail of customer tools or skills to call lnav through external access and do its magic.

This is exactly how I do and it works when interactively using "lnav", but I want to achieve something similar programmatically.

I can use the external access to run lnav commands (:whatever) , and scripts (|whatever), but not SQL apparently.

To Reproduce

By using the ":external-access" feature I can successfully setting things up once on the "lnav server" side :

# lnav -n -c ":external-access 6666 abc123" /var/log/messages

And then use "curl" to query the lnav API version :

# echo -n "abc123" | base64
YWJjMTIz

# curl --include --header "X-Api-Key: YWJjMTIz" -X GET http://localhost:6666/api/version
HTTP/1.1 200 OK
Server: tiny-http (Rust)
Date: Fri, 29 May 2026 23:05:33 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 50

{"product":"lnav","version":"0.14.1","pid":919162}

The documentation in the External Access (v0.14.0+) seems to refer to "scripts" only, but I can run lnav commands fine (as long as I drop the colon) :

# curl -X POST   -H "X-Api-Key: YWJjMTIz"   -H "Content-Type: text/x-lnav-script"   -d 'filter-in tcp'   http://localhost:6666/api/exec
# curl -X POST   -H "X-Api-Key: YWJjMTIz"   -H "Content-Type: text/x-lnav-script"   -d 'write-view-to /tmp/output.txt'   http://localhost:6666/api/exec
# cat /tmp/output.txt 
May 24 06:54:14 desktop systemd-resolved[1328]: Closing all remaining TCP connections.
May 24 19:40:50 desktop systemd-resolved[1328]: Closing all remaining TCP connections.
May 26 09:07:21 desktop systemd-resolved[1328]: Closing all remaining TCP connections.
May 27 01:13:05 desktop systemd-resolved[1328]: Closing all remaining TCP connections.
May 27 16:29:44 desktop systemd-resolved[1328]: Closing all remaining TCP connections.
May 29 17:04:10 desktop systemd-resolved[1328]: Closing all remaining TCP connections.
May 29 23:38:37 desktop systemd-resolved[1328]: Closing all remaining TCP connections.

Scripts work fine as well (at least, there is an error returned when the syntax is wrong and nothing when it is right) :

# curl -X POST   -H "X-Api-Key: YWJjMTIz"   -H "Content-Type: text/x-lnav-script"   -d '|find-msg next syslog_log log_pid'   http://localhost:6666/api/exec

However, when running SQL no results are at all returned, but no errors are given by the SQL command, for example :

# curl -X POST   -H "X-Api-Key: YWJjMTIz"   -H "Content-Type: text/x-lnav-script"   -d ';SELECT * FROM logline'   http://localhost:6666/api/exec
# curl -X POST   -H "X-Api-Key: YWJjMTIz"   -H "Content-Type: text/x-lnav-script"   -d 'write-table-to /tmp/output.txt'   http://localhost:6666/api/exec
{"msg":"no query result to write, use ';' to execute a query","reason":"","help":":write-table-to [--anonymize] path\n══════════════════════════════════════════════════════════════════════\n  Write SQL results to the given file in a tabular format"}

Starting "lnav" with the ":external-access" enabled and the TUI to see the results from outside commands, running SQL does nothing (interface is not updated at all).

But I noticed one difference : when running valid external SQL, nothing is printed in the TUI. When running invalid SQL; the command is printed and the error is shown in the TUI :

#### From the client
# curl -X POST   -H "X-Api-Key: YWJjMTIz"   -H "Content-Type: text/x-lnav-script"   -d ';SELECT * FROM invalid_table'   http://localhost:6666/api/exec
{"msg":"failed to compile SQL statement","reason":"no such table: invalid_table","help":""}

#### On the lnav TUI
ⓘ info: Executing command at 127.0.0.1:45790:1 — ;SELECT * FROM invalid_table

What's being asked from the developer

• First, the documentation should be more clear in stating what you can do (because it now refers to commands and scripts interchangeably)
• I fail to understand if the need to drop the colon in the commands when calling external access is a feature or a bug
• It appears to me SQL is supposed to work, but it doesn't, this would be a defect
• Finally, wondering if my use case is adequate for this feature, or I should wait for something which may be more suited to it, like the feature to give lnav some MCP abilities

[tstack]

However, when running SQL no results are at all returned, but no errors are given by the SQL command, for example:

Try putting all of the commands in a single request. I think curl can read from a file and send that as the body of the request.

What is probably happening is that the SQL query you did generated results that were then dropped when the request finished.

[dardhal]

Yes, it works like you said, a couple examples :

#### Input file is this big
# wc -l /var/log/messages 
8681 /var/log/messages

#### Applying an IN filter first, then writing results to a text file
# curl -X POST   -H "X-Api-Key: YWJjMTIz"   -H "Content-Type: text/x-lnav-script"   -d $':filter-in tcp\nwrite-view-to /tmp/example.txt'   http://localhost:6666/api/exec
# wc -l /tmp/example.txt
7 /tmp/example.txt

#### Now I want to run SQL and store output as CSV (there is one additional line, which is the CSV header)
# curl -X POST   -H "X-Api-Key: YWJjMTIz"   -H "Content-Type: text/x-lnav-script"   -d $';SELECT * FROM syslog_log\n:write-csv-to /tmp/example.csv'   http://localhost:6666/api/exec
# wc -l /tmp/example.csv
8 /tmp/example.cs

You can also read the list of commands from file :

# cat /tmp/lnav.commands
:reset-session
;SELECT * FROM syslog_log
:write-csv-to /tmp/example.csv

# curl -X POST -H "X-Api-Key: YWJjMTIz" -H "Content-Type: text/x-lnav-script" --data-binary @/tmp/lnav.commands http://localhost:6666/api/exec
# wc -l /tmp/example.csv 
8682 /tmp/example.csv

A few remarks here :

• Prior testing showing the first command in the list of commands returns error if using the colon, but that seems to have been some error on my side
• When using curl --data option for the list of commands in the command line itself, at least from BASH you need to use $'' for the new line characters separating the commands to be interpreted right
• To read the commands from a file, you need to use curl's --data-binary, else if using --data the carriage returns, newlines and null bytes are stripped out (from CURL man page)

So things seems to work well, the only thing I would suggest addressing is the documentation to be a bit more detailed about how to use this feature (although I hope this issue can be found by others searching for the same information).

Still wondering how "lnav" acting as an MCP provider may eventually be delivered, if at all, but this ":external-access" thingy is already so useful for me to integrate in some very interesting log analysis workflows.

[tstack]

Let's keep this open until the documentation has been updated.

[tstack]

I would prefer loading up all the necessary input files, and repeatedly work on the indexed files, running as many scripts or commands as I want.

This usage was one of the reasons to add the external-access stuff.

The ultimate goal is to leverage lnav as a short of resident log parsing, processing and analysis service, to be called from some AI-based agent

That does seem to be where the world is heading. Acting as an MCP server is on the to-do list, but I haven't gotten there yet.

(sometimes several scripts with different parameters)

Have you tried putting some of these scripts into a Markdown file and running it from an App?

When you turn on external-access, a globe icon shows up in the top-right. When you click on that it will open a browser that is connected to the lnav external-access port. The index page shows the list of apps and the "api-test" app contains some canned lnav scripts. You can also add some HTML to create a primitive form and the results can be charted.

Here is the source of the "api-test" app:

https://github.com/tstack/lnav/blob/master/src/static-files/apps/lnav/api-test/index.md?plain=1

I'd be interested to know if it works beyond my basic testing.

[dardhal]

Have you tried putting some of these scripts into a Markdown file and running it from an App?

When you turn on external-access, a globe icon shows up in the top-right. When you click on that it will open a browser that is connected to the lnav external-access port. The index page shows the list of apps and the "api-test" app contains some canned lnav scripts. You can also add some HTML to create a primitive form and the results can be charted.

Here is the source of the "api-test" app:

https://github.com/tstack/lnav/blob/master/src/static-files/apps/lnav/api-test/index.md?plain=1

I'd be interested to know if it works beyond my basic testing.

It is definitely something I will have to look into, because I have sadly experienced that no matter how easy you can make "lnav" to use and how much I try to "sell" my users into the benefits of using it (with extensive internal documentation, customization and examples), the fact is there has been little adoption due to a perceived steep learning curve. For some, just "living" on the terminal is hard enough to ask too much else from them.

If I can make users just go to a web page , fill in a case number, and a web interface giving them some options to choose from, that can help them a lot (there will be some SSH tunnel scaffolding needed for users to be able to access "lnav" from their desktops as "lnav" will be run remotely).

On the other hand the agentic log /problem analysis with "lnav" as the backend is the current approach we are exploring, but so far this is based on the terminal and hence the web access would not be that useful.

Either case will give this a try and report as soon as I have something to share.