plugin_file_put

Create or overwrite a text file in a plugin’s files/ folder. Missing parent folders are created. The plugin’s own code can’t read these files; they are for the operator.

Request

{
  "cmd": "plugin_file_put",
  "name": "hello",
  "path": "notes/today.md",
  "content": "Shipped the ping responder."
}

Field	Type	Required	Description
name	string	Yes	Plugin name. 1 to 64 letters, digits, _, or -.
path	string	Yes	File path relative to files/, 1 to 256 characters. It must stay inside the folder: a path that climbs out with .. is rejected.
content	string	Yes	The full new contents. At most 262,144 characters (256 KiB). An empty string is allowed.

Response

{
  "cmd": "plugin_file_put",
  "val": true
}

The file is replaced in one step, so a reader never sees a half-written file. The write and its path are recorded in the audit log.

Caution

The server doesn’t check that the plugin is installed. Writing to an unknown name creates a plugin folder with no manifest. That folder then blocks plugin_install under the same name until you remove it with plugin_uninstall.

Permissions

Requires manage_server. It is blocked while you are timed out.

Errors

val	When
Invalid plugin file path	path is . or resolves to somewhere outside files/.
Unable to create plugin file directory	The server couldn’t create a parent folder.
Unable to save plugin file	The server couldn’t write the file.
Validation message	A field is missing or too long, for example content: Expected length at most 262144.

See also

• plugin_file_get
• plugin_file_list