Host API

The Lua sandbox exposes a single host table named waydir. Functions either do small synchronous work inside the sandbox or emit effects that the Flutter host applies after run(ctx) returns.

Functions

Call	Permission	Effect
waydir.toast(msg)	none	Shows a short toast message.
waydir.notify({ title, message, level, persistent })	none	Creates a notification. level can be info, success, warn, or error.
waydir.dialog({ title, fields, submit_action })	none	Shows a form and re-runs the action with ctx.form.
waydir.set_setting(key, value)	none	Persists one setting value for this plugin.
waydir.refresh()	none	Refreshes the current file list.
waydir.log(msg)	none	Writes to the Waydir log.
waydir.exec(cmd, args)	exec	Runs a short external command and waits for it.
waydir.run_task({ title, cmd, args, cwd, timeout })	exec	Runs a long external command outside the Lua sandbox.
waydir.read_text(path)	fs	Reads a UTF-8 text file, capped at 4 MiB.
waydir.write_text(path, text)	fs	Writes a text file.
waydir.mkdir(path)	fs	Creates a directory and parents.
waydir.exists(path)	fs	Returns whether a path exists.
waydir.list(path)	fs	Lists a directory as { name, path, is_dir } rows.
waydir.copy(src, destDir)	fs	Queues a copy into destDir using Waydir operations.
waydir.move(src, destDir)	fs	Queues a move into destDir using Waydir operations.
waydir.delete(path)	fs	Queues a permanent delete with host-side confirmation.
waydir.trash(path)	fs	Queues a move to trash with host-side confirmation.

Notifications

waydir.notify({
  title = "New from Template",
  message = "Created README.md",
  level = "success",
  persistent = false,
})

title is optional. message is required.

Quick commands

Use waydir.exec for short commands only.

waydir.exec("code", { ctx.dir })

Non-zero exit codes are logged. Missing binaries or process launch errors fail the plugin invocation.

Long tasks

Use waydir.run_task for compression, conversion, extraction, uploads, or anything that may be slow.

waydir.run_task({
  title = "Extract archive",
  cmd = "7z",
  args = { "x", "/tmp/archive.zip", "-o/tmp/archive", "-y" },
  cwd = ctx.dir,
  timeout = 3600,
})

Task timeout is in seconds. If omitted, Waydir uses 600 seconds. The maximum is 21600 seconds.

File operations

The direct file helpers (read_text, write_text, mkdir, exists, list) run in the native plugin runtime and require fs.

The queued operations (copy, move, delete, trash) are applied through Waydir's normal operation system, so they get progress, cancellation, and host confirmation for destructive actions.

Sandbox limits

Limit	Value
Lua standard libraries	table, string, math
Missing libraries	os, io, require
Load timeout	5 seconds
Invoke timeout	5 seconds
read_text cap	4 MiB

Each run starts with a fresh Lua VM. Do not rely on module-level variables persisting between clicks.