Skip to content

Documentation / Reference

Reference

Exact field names, limits, environment variables, errors, and transport behavior for API and plugin authors.

Manifest fields

Field	Type	Required	Rules
`activationEvents`	string[]	yes	`onStartup`, `onCommand:<id>`, or `onPanel:<id>`. Contributions require matching activation events.
`arguments`	string[]	yes	Arguments passed directly to the executable. At most 64 entries and 4 KiB per entry.
`contributes`	object	yes	Bounded command and panel declarations rendered by Cairn.
`executable`	string	yes	Relative executable path inside the plugin directory. Absolute paths and directory escapes are rejected.
`id`	string	yes	Reverse-DNS identifier with at least three components; it must also be the plugin directory name.
`manifestVersion`	integer (= 1)	yes	Manifest schema version. The current value is generated from `PluginManifest.currentManifestVersion`.
`name`	string	yes	Human-readable name, at most 120 UTF-8 bytes.
`permissions`	string[]	yes	Capabilities requested by the plugin. Declaration does not grant access.
`version`	string	yes	Plugin release version, at most 80 UTF-8 bytes.

Contribution fields

`contributes`

Field	Type	Required	Rules
`commands`	command[]	yes	At most 128 command-palette contributions with unique IDs.
`panels`	panel[]	yes	At most 32 dock-panel contributions with unique IDs.

Command

Field	Type	Required	Rules
`description`	string?	no	Optional detail shown with the command; at most 500 UTF-8 bytes.
`id`	string	yes	Contribution identifier, at most 80 allowed ASCII characters.
`systemImageName`	string?	no	Optional SF Symbol name, at most 120 UTF-8 bytes.
`title`	string	yes	Command title, at most 120 UTF-8 bytes.

Panel

Field	Type	Required	Rules
`buttons`	button[]	yes	At most eight buttons with unique IDs.
`id`	string	yes	Contribution identifier, at most 80 allowed ASCII characters.
`rows`	row[]	yes	At most 32 read-only label/value rows.
`status`	status?	no	Optional host-rendered status treatment.
`systemImageName`	string	yes	SF Symbol name, at most 120 UTF-8 bytes.
`title`	string	yes	Panel title, at most 120 UTF-8 bytes.

Panel row

Field	Type	Required	Rules
`label`	string	yes	Row label, at most 120 UTF-8 bytes.
`value`	string	yes	Row value, at most 1,000 UTF-8 bytes.

Panel status

Field	Type	Required	Rules
`level`	enum	yes	`neutral`, `success`, `warning`, or `error`.
`text`	string	yes	Status text, at most 500 UTF-8 bytes.

Panel button

Field	Type	Required	Rules
`id`	string	yes	Unique contribution identifier.
`role`	enum	yes	`normal`, `primary`, or `destructive`.
`title`	string	yes	Button title, at most 120 UTF-8 bytes.

Transport and limits

Local API	`json-rpc-2.0+ndjson+unix`; owner-only Unix socket and token/metadata files.
Plugin transport	`json-rpc-2.0+ndjson+stdio`; stdout is protocol-only, stderr is diagnostics.
Record size	4 MiB before the newline on both transports. Oversized local records close the connection; plugin violations terminate that plugin.
Request IDs	Local API accepts string, integer, or null IDs. Cairn-to-plugin requests use integer IDs.
Params	JSON-RPC request params must be an object or array.
Schema digest	`929d09094fbc6efff173f93f45cb1203de9b6d31001a990df26485ebe7f930a7`

JSON-RPC errors

Code	Meaning
`-32700`	Parse error
`-32600`	Invalid request
`-32601`	Method not found
`-32602`	Invalid params
`-32603`	Internal error
`-32001`	Authentication required
`-32002`	Capability not granted
`-32003`	Request exceeds 4 MiB
`-32004`	Authentication failed
`-32005`	Session already authenticated
`-32006`	Descriptor already registered