====== Scripting ======

Scripts can use Python or bundled Lua 5.4.9. Choose a ''.py'' or ''.lua'' file in **Script → Run**; logon scripts, saved script commands and ''--script'' also accept both. Use **Script → Cancel** to stop the current tab’s worker. Script errors appear in the Activity pane. A session that is still logging in counts as open, so a script can wait for a password, passphrase or host-key prompt and answer it with ''Send''. The [[https://retro.theiguru.au/lantern-terminal/docs/LUA-SCRIPTING.md|Lua scripting guide]] includes its syntax and API reference.

===== Python =====

Choose **Script → Run** and select a ''.py'' file. Python runs separately from the desktop UI. The application passes a private, per-instance local connection token and the originating tab ID; changing focus does not retarget the script. Cancellation terminates the script process and leaves the connection open.

Linux uses configured/system Python 3. Windows packages include a private Python runtime. Select a different interpreter under Global Settings → Automation if needed. The ''lantern'' module uses only the standard library.

<code python>
from lantern import app

tab = app.GetScriptTab()
tab.Screen.Send("printf '%s%s\\n' 'terminal-' 'ready'\r")
if not tab.Screen.WaitForString("terminal-ready", 5):
    raise TimeoutError("Endpoint did not respond")
print(tab.Caption, tab.Screen.Rows, tab.Screen.Columns)
</code>

Build test prompts from pieces so a wait does not match its own echoed command line. A screen send records the incoming-stream position before transmission, so an immediate reply is retained for the following wait.

===== Included interface =====

  * ''app.Version'', ''app.Arguments.Count/GetArg(0)'', ''app.GetScriptTab()'', ''app.GetActiveTab()'', ''app.GetTabCount()'', ''app.GetTab(1)'', ''app.Sleep(milliseconds)'' and ''app.Quit()''.
  * Tabs: ''Caption'', one-based ''Index'', ''Screen'', ''Session'', ''Activate()'', ''Clone()'', ''Close()'', ''ConnectSftp()'', ''ResetCaption()'', ''ZmodemUpload(files)'' (queue files for the host's Zmodem receiver), ''ZmodemCancel()'', ''ZmodemActive()''.
  * Screen: ''Rows'', ''Columns'', one-based ''CurrentRow/CurrentColumn'', ''Selection'', ''Send(text)'', binary ''SendBytes(data)'', ''Get/Get2(top,left,bottom,right)'', ''Clear()'', ''SendKeys()'', ''SendSpecial()'', ''WaitForCursor()'', ''WaitForString()'', ''WaitForStrings()'' and ''ReadString()''.
  * Matching: ''IgnoreCase'', capture ''IgnoreEscape'', ''Synchronous'' and ''MatchIndex''. Wait timeouts default to seconds; zero waits until match/disconnect/cancellation. ''WaitForStrings'' returns one-based index or zero on timeout; ''WaitForString'' returns a boolean. ''ReadString'' excludes the matched delimiter and returns empty text on timeout.
  * Session: ''Connected'', ''Logging'', ''LogFileName'', ''Config'', ''Disconnect()'', ''Connect(profile)'', ''ConnectInTab(profile)'', and ''Log(enabled, append, raw)''.
  * Configuration: ''GetOption(key)'', ''SetOption(key,value)'' and ''Save()''. Keys are the typed application keys in ''src/config.cpp'', such as ''fontSize'', ''logPath'', ''host'', ''port'' and ''keyFile''.
  * Clipboard: ''app.Clipboard.Text''.
  * Dialogs: ''app.Dialog.MessageBox(text,title)'', ''Prompt(text,title,default,password)'' and ''FileOpenDialog(title)''.

''Get2'' retains line separators; ''Get'' concatenates lines. Closed/locked sessions and invalid coordinates produce explicit errors. A session disconnected while waiting raises ''LanternError''. Capture is bounded; truncation raises an error rather than silently dropping the beginning of a response.

The comprehensive SCRIPTING-API.md defines the larger API contract. Members outside the included interface above are not supplied by this release. Lua uses the same authenticated application API through its bundled worker; see LUA-SCRIPTING.md for language-specific details.

[[lanternterminal:start|Back to Lantern Terminal]]