# 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. The [Lua scripting guide](LUA-SCRIPTING.md) 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.

```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)
```

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`. 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`; `Session.Connected` becomes true only after authentication. 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.