Table Shapes

Some functions return (or accept) a Lua table with a fixed set of keys, such as the response of Rest.get. Each such table shape is described once here; function pages link to it.

AgentSessionResult

The result of a message sent in a CLI agent session.

Fields

success boolean: true when the CLI exited with code 0
exit number: process exit code
text string: the answer of the agent
all string: the complete CLI output
duration number: run time in milliseconds
sessionId string: id of the session, nil until the CLI reports it
messages any[]: the answer messages as a list of strings

Used by

AgentTaskResult

The result of a one-off task run with a CLI agent library (Codex, Copilot, OpenCode).

Fields

success boolean: true when the CLI exited with code 0
exit number: process exit code
text string: the final answer of the agent
all string: the complete CLI output
duration number: run time in milliseconds

Used by

CouchResponse

The response of a CouchDB request made with Couch. A non-2xx status is not an error: CouchDB reports problems in the body ({"error": "not_found", "reason": "missing"}), so check status yourself.

Fields

status number: HTTP status code, for example 200, 201 or 404
json string: the response body as pretty-printed JSON text
table table: the response body decoded into a Lua table (the same data as json)

Used by

DashboardTextOptions

A piece of dashboard text and how to show it. Only value is required. Headers ignore size (their size is the second argument of Dashboard.h).

Fields

value string: the text to show
color string optional: text color as a CSS color, for example red or #ff8800; default is the page color
background string optional: background color as a CSS color; default is none
size number optional: font size in pixels, a number; default is the page font size

Used by

DownloadResponse

The result of Rest.download: the response metadata, with the body saved to a file. The status is not checked, so a 404 or 500 body is saved too.

Fields

status number: HTTP status code, for example 200 or 404
file string: path of the saved file, relative to the project, with forward slashes
size number: size of the saved file in bytes
body string: always an empty string (the body is in the file)
response string: always an empty string (the body is in the file)
headers table: response headers by name. Each header is present under its original name and under its lower-case name. The value is a string, or a list of strings when the header occurred more than once
cookies RestCookie[]: all cookies in the Rest cookie jar after this response

Used by

Rest.download()

FileStat

Metadata of a file or directory, returned by Fl.stat. For a path that does not exist only path and exists (false) are set.

Fields

path string: the path relative to the workspace, with forward slashes (the workspace itself is .)
exists boolean: whether the path exists
name string optional: the last part of the path
type string optional: file, directory or other (for example a device)
isFile boolean optional: true for a regular file
isDirectory boolean optional: true for a directory
size number optional: size in bytes (for a directory this is whatever the file system reports, not the size of its content)
modifiedAt string optional: last modification time as an ISO 8601 instant in UTC, for example 2026-01-31T12:30:00.123Z
createdAt string optional: creation time as an ISO 8601 instant in UTC; some file systems report the modification time
accessedAt string optional: last access time as an ISO 8601 instant in UTC
parent string optional: the path of the containing directory relative to the workspace; left out when it lies outside the workspace

Used by

Fl.stat()

HttpResponse

The response of an HTTP request made with Rest. A non-2xx status is not an error: check status yourself.

Fields

status number: HTTP status code, for example 200 or 404
body string: response body decoded as UTF-8 text, empty when the response has no body
response string: same value as body (older scripts use this name)
headers table: response headers by name. Each header is present under its original name and under its lower-case name (headers["content-type"]). The value is a string, or a list of strings when the header occurred more than once (such as Set-Cookie)
cookies RestCookie[]: all cookies in the Rest cookie jar after this response, not only those set by this response

Used by

MailAttachment

Metadata of an attachment of a mail message. Inline images that are referenced by the HTML body (they have a Content-ID) are not counted as attachments.

Fields

filename string: attachment file name, decoded; empty when the part has none
content_type string: MIME content type, for example application/pdf; name="invoice.pdf"
size number: size in bytes as reported by the server, 0 when unknown

MailboxSettings

Connection settings for Mail.imap and Mail.pop. Any other key of the table is passed to JavaMail as a property, so you can add for example ["mail.imap.connectiontimeout"] = 10000 or ["mail.imap.ssl.trust"] = "mail.example.com".

Fields

host string: mail server host name (required; also accepted as mail.imap.host or mail.pop3.host)
user string: user name to log in with (required; also accepted as username)
password string: password to log in with (required; use secret())
port number optional: server port. Defaults: IMAP 993 with SSL and 143 without, POP3 995 with SSL and 110 without
ssl boolean optional: connect over SSL/TLS from the start. Default: true for IMAP and for ports 993 and 995, false for POP3 and for ports 143 and 110
starttls boolean optional: upgrade a plain connection with STARTTLS; default false
folder string optional: folder to open first; default INBOX (also accepted as mailbox). POP3 only has INBOX

Used by

MailMessage

A message read from a mailbox. Text fields that the message does not have are empty strings, never nil. Reading a message does not change it on the server (the mailbox is opened read-only), so seen is not set by reading.

Fields

number number: sequence number in the folder (1 is the oldest message); use it with Mailbox.get and Mailbox.downloadAttachments. It can change when messages are added or removed, so do not store it
folder string: name of the folder the message was read from
subject string: subject line, decoded
message_id string: value of the Message-ID header
from any[]: sender addresses, each as the server gives it: a display name followed by the address in angle brackets, or just the address (alice@example.com)
to any[]: recipients in the To header, formatted like from
cc any[]: recipients in the Cc header
bcc any[]: recipients in the Bcc header; normally empty because senders' Bcc headers are not kept
reply_to any[]: addresses replies should go to
sent_at number: Date header as a Unix timestamp in milliseconds, 0 when missing
sent_at_iso string: Date header as an ISO 8601 UTC time such as 2025-03-01T08:30:00Z, empty when missing
received_at number: time the server received the message, in Unix milliseconds, 0 when unknown
received_at_iso string: time the server received the message as ISO 8601 UTC, empty when unknown
size number: message size in bytes as reported by the server, 0 when unknown
content_type string: MIME type of the whole message, for example multipart/mixed; boundary=...
body string: the plain text of the message; when it has no plain text part, the HTML source of the HTML part (not converted to text)
text string: all text/plain parts joined, empty when there is none
html string: all text/html parts joined, empty when there is none
attachments MailAttachment[]: metadata of the attachments (use Mailbox.downloadAttachments to save the files)
has_attachments boolean: true when attachments is not empty
seen boolean: the message has been read (always false on POP3, which has no flags)
answered boolean: the message has been answered
deleted boolean: the message is marked as deleted
draft boolean: the message is a draft
flagged boolean: the message is flagged
recent boolean: the message arrived since the last session (IMAP only)

Used by

MailSearch

Search criteria for Mailbox.search and Mailbox.poll. Every key is optional and all given criteria must match. Text criteria are "contains" matches, ignoring case; they are not regular expressions. The search runs in the agent on messages it has downloaded, not on the server.

Fields

query string optional: text that must appear in the subject, sender, To recipients, body or Message-ID
subject string optional: text that must appear in the subject
from string optional: text that must appear in the sender, including the display name (searching for alice finds a sender with the display name Alice Smith)
to string optional: text that must appear in the To recipients (Cc and Bcc are not searched)
body string optional: text that must appear in the body (the plain text, or the HTML source when there is no plain text)
messageId string optional: text that must appear in the Message-ID header (also accepted as message_id)
seen boolean optional: true for only read messages, false for only unread ones (always unread on POP3)
unseen boolean optional: the opposite of seen; ignored when seen is given
hasAttachments boolean optional: true for only messages with attachments, false for only messages without (also accepted as has_attachments)
since string optional: only messages received on or after this moment. A date or date-time string (2025-03-01, 2025-03-01T08:00:00, 2025-03-01T08:00:00Z; without zone the agent's time zone applies) or a Unix timestamp in seconds or milliseconds. Messages without a received date never match
before string optional: only messages received before this moment, same formats as since
limit number optional: return at most this many messages; 0 or left out means no limit. Results are newest first

Used by

RestCookie

A cookie stored in the Rest session.

Fields

name string: cookie name
value string: cookie value
domain string: domain the cookie applies to
path string: path the cookie applies to
secure boolean: only sent over HTTPS
httpOnly boolean: not readable by page scripts
persistent boolean: the cookie has an expiry date
expiry string: expiry date in ISO 8601, nil for session cookies

Used by

Rest.cookies()

SharepointItem

A file or folder in a SharePoint document library.

Fields

name string: file or folder name
path string: path relative to the library root; pass it to download, move or delete
folder boolean: true for a folder, false for a file
size number: size in bytes
webUrl string: browser URL of the item
lastModified string: last modified date in ISO 8601

Used by

SharepointSite.list()

SmtpSettings

SMTP settings for Mail.properties. Besides the short keys below, every other key of the table is handed to JavaMail as a property, so any mail.smtp.* property works, written as a quoted key (for example ["mail.smtp.connectiontimeout"] = 10000 or ["mail.smtp.ssl.trust"] = "smtp.example.com"). The short keys host, port, auth, starttls and ssl are aliases for mail.smtp.host, mail.smtp.port, mail.smtp.auth, mail.smtp.starttls.enable and mail.smtp.ssl.enable; when both forms are present the mail.smtp.* key wins. Timeouts (["mail.smtp.connectiontimeout"] and ["mail.smtp.timeout"], in milliseconds) default to waiting forever. Values may be strings, numbers or booleans; they are converted to strings.

Fields

host string optional: SMTP server host name (alias for mail.smtp.host). Without it JavaMail tries localhost
port number optional: server port (alias for mail.smtp.port); JavaMail's default is 25
auth boolean optional: log in with user and password (alias for mail.smtp.auth). Without it no login is attempted
starttls boolean optional: upgrade the connection with STARTTLS, usually port 587 (alias for mail.smtp.starttls.enable)
ssl boolean optional: encrypt from the start, usually port 465 (alias for mail.smtp.ssl.enable)
user string: user name to log in with, also used as the sender address of every mail, so it should be a full address such as bot@example.com (also accepted as username or mail.smtp.user)
password string: password to log in with (also accepted as mail.smtp.password); use secret()

Used by

Mail.properties()

SshResult

The outcome of a command run with session.run. A non-zero exit code is not an error: check exitCode yourself.

Fields

exitCode number: exit code of the command; 0 means success, -1 when the server did not report one
stdout string: everything the command wrote to standard output
stderr string: everything the command wrote to standard error

Used by

SshSession.run()

TelegramCallback

A press on an inline keyboard button.

Fields

id string: callback query id (pass it to TelegramBot.ack)
data string: the callback_data of the pressed button
from TelegramUser: the user who pressed the button
message TelegramMessage: the message the button belongs to

TelegramMessage

A message that was sent to or received from a Telegram chat.

Fields

message_id number: Telegram message id
chat_id number: id of the chat the message belongs to
text string: message text
date number: unix timestamp (seconds) when the message was sent

Used by

TelegramReply

A text reply received in the chat.

Fields

message_id number: Telegram message id
chat_id number: id of the chat the reply was sent in
text string: reply text
from TelegramUser: the sender, when known

Used by

TelegramBot.waitReply()

TelegramUpdate

One update from the Telegram bot API.

Fields

update_id number: update id
message TelegramMessage: the new message, when the update is a message
callback_query TelegramCallback: the button press, when the update is a callback

Used by

TelegramBot.poll()

TelegramUser

A Telegram user or bot.

Fields

id number: Telegram user id
username string: user name without the @
first_name string: first name (only present in the bot info returned by TelegramBot.me)

Used by

TelegramBot.me()