divekit run

Execute a single Lua script for custom automation. The command resolves a script by name from trusted directories or accepts an absolute path.

Usage

divekit run <script|/absolute/path/to/script.lua>

• Exactly one argument is required.
• When a name (without path) is provided, Divekit searches in trusted directories.
• When an absolute path is provided, the script is executed directly (if it exists and is a .lua file).

Script Resolution

Resolution happens in this order:

1. Absolute path (when you pass an absolute path)

• Accepted as-is if it points to an existing .lua file.

2. Trusted directories in the current Divekit project (highest priority)

• .divekit/scripts/
• .divekit/lua/
• .divekit/hooks/

3. Trusted directories in the user’s home

• ~/.divekit/scripts/
• ~/.divekit/lua/
• ~/.divekit/hooks/

For name-only arguments (e.g., my-script), Divekit will try both my-script and my-script.lua in each trusted directory.

Security and Guards

• Only .lua files are executed.
• Symlinks are resolved and the resolved path must remain within the trusted root being checked (prevents path traversal).
• Relative paths are not executed directly; they must resolve from trusted directories.

Examples

Run by name (search in trusted locations)

# Looks up ".divekit/scripts/my-script.lua", then other trusted directories
divekit run my-script

Run by name with extension

divekit run my-script.lua

Run by absolute path

divekit run /full/path/to/my-script.lua

Run a script from the user’s home

# If placed under ~/.divekit/lua/report.lua
divekit run report

Troubleshooting

• Script not found:
  • Ensure the file exists in one of the trusted directories or pass an absolute path.
  • If using a name, try adding the .lua extension.
• Permission denied:
  • Check file permissions and ownership of the script file.
• Wrong file type:
  • Only .lua files are accepted.

Notes

• This command executes a single Lua file; there are no additional subcommands or flags for run.
• If your script depends on project context, run the command from inside a Divekit project (a directory that contains .divekit/).