Manifest reference

plugin.toml declares a plugin's identity, listing behavior, permissions and actions. It sits next to Cargo.toml in the source and at the root of the installed package.

lla validates the same rules three times: export_plugin! and export_component! at compile time, lla install, and package discovery when a plugin loads. Unknown keys are ignored, so a misspelled optional key produces no error.

Complete example

This manifest compiles, installs and passes lla plugin doctor.

schema_version = 3
 
[plugin]
id = "dev.example.my-plugin"
name = "my_plugin"
version = "1.0.0"
api_min = 3
api_max = 3
runtime = "native"
entrypoint = "my_plugin"
description = "Inspect files"
license = "MIT"
repository = "https://github.com/example/my-plugin"
 
[capabilities]
decorates_entries = true
formats = ["default", "long"]
machine_output = true
 
[permissions]
filesystem = ["metadata:selection", "read:user-path"]
network = ["api.example.com"]
process = false
clipboard = false
open_url = false
 
[[fields]]
name = "score"
type = "integer"
sortable = true
filterable = true
description = "Score derived from file size"
 
[[actions]]
id = "inspect"
description = "Inspect one or more paths"
examples = ["lla plugin run my_plugin inspect -- README.md --depth 2"]
interactive = false
arguments = [
  { name = "paths", type = "path", description = "Paths to inspect", position = 0, required = true, repeatable = true },
  { name = "depth", type = "integer", description = "Levels to descend", option = "--depth", default = 1, min = 0, max = 8 },
  { name = "mode", type = "string", description = "Inspection mode", option = "--mode", choices = ["quick", "full"] },
  { name = "hidden", type = "boolean", description = "Include hidden files", option = "--hidden", default = false },
]
output = { type = "table", columns = [
  { name = "path", type = "path", description = "Inspected path" },
  { name = "bytes", type = "bytes", description = "Size in bytes" },
] }

Top level

Several keys below are identifiers. An identifier is non-empty and contains only ASCII letters, digits, ., _ and -.

[plugin]

entrypoint works differently per runtime:

A source install finds native libraries in target/release by matching the Cargo package name with - replaced by _. Keep the three names aligned: package file-score, [lib] name = "file_score" and entrypoint = "file_score".

[capabilities]

Any string passes validation in formats, but the host only sends the values below. A view missing from formats never calls the plugin.

The table view normalizes to long, so declaring table has no effect.

[permissions]

Native plugins run fully trusted, so these keys are declarations that lla plugin info displays. A WebAssembly component only gets what the user approved, and the scopes control what it can reach.

For a selected entry, lla preopens the entry's parent directory. With a scope marked Tree below, a selected directory is preopened itself. For a user path, meaning a path value in an action's arguments, lla preopens the path's parent directory. A path containing .. is rejected.

delete:quarantine passes validation and opens nothing.

Runtime network checks compare the request's host with each entry exactly, and the comparison is case-sensitive.

[[fields]]

If a plugin sets a display string for a declared field and no typed value, the host converts the string to the declared type. lla plugin doctor fails with field 'score' cannot be converted to its declared Integer type when it can't.

[[actions]]

Arguments

default and choices values match type as follows:

The host parses action arguments against this schema before it calls the plugin:

A repeatable positional collects every remaining positional token, and a repeatable option accepts the flag more than once. The host fills in default when you omit an argument, so the plugin receives it as if you had typed it.

Output

The host doesn't check the contents of schema against the returned value. It does check that the returned output kind matches the declared type, and fails with action 'inspect' returned output that does not match plugin.toml when it doesn't.

Each entry in columns:

Table rows are checked strictly. Column names must match in order, each row needs one cell per column, and each cell's type must match exactly, so a bytes column needs value::bytes. A violation fails with action 'inspect' returned a table that violates its column schema.

Package integrity

The installer writes checksums.toml into each package. You don't write it by hand.

[files]
"libfile_score.dylib" = "<64 hex characters>"
"plugin.toml" = "<64 hex characters>"

The table must cover the entrypoint and plugin.toml. Paths are relative and name regular files. Symlinks are rejected. Each value is a SHA-256 digest of 64 hex characters.

Validation errors