add an HTTP API

Author: idankCreated Dec 5, 2013Updated Aug 18, 2026

It might be time to add an HTTP API for tools/websites that want to integrate with explainshell (issue #4 is one).

My current thought is to add a GET endpoint at /api/explain with a cmd parameter, similar to /explain. The response could be a JSON that looks something like this:

{
  'help' : ['help text 0', 'help text 1', ..],
  'cmd' : <parsed command>
  'matches' : [{'startindex' : x,
                    'endindex' : y,
                    'helpindex' : <index into help array, or -1 if unknown>], [..]]
}

The rationale for not inlining the help text into matches is that there can be duplicates. The reason for including cmd in the response is that it's possible for explainshell to change it, e.g. due to unicode which is not supported yet.

Example:

GET /api/explain?cmd=echo -n

{
  'help' : ['display a line of text',
             '-n     do not output the trailing newline'],
  'cmd' : 'echo -n'
  'matches' : [{'startindex' : 0, 'endindex' : 4, 'helpindex' : 0},
                   {'startindex' : 5, 'endindex' : 7, 'helpindex' : 1}]
}