Examples

Official Swift client

// The repository ships this production client:
// scripts/developer-tools/cairnctl.swift
//
// Compile it directly:
// xcrun swiftc -O cairnctl.swift -o cairnctl
//
// Discover + authenticate + describe:
// ./cairnctl describe

The client resolves control.json, reads its token, connects with a native Unix socket, sends the capability-scoped handshake, enforces the 4 MiB record limit, and prints canonical JSON responses.

Bash invocation

# The wrapper compiles and caches the Swift client outside the repo.
./scripts/cairnctl describe
./scripts/cairnctl ping '{"sequence":42}'
./scripts/cairnctl call plugins/list '{}' --capability plugins.read
./scripts/cairnctl subscribe api/catalogChanged

Install the Bash plugin

plugin_id=com.example.cairn.hello
plugin_root="${CAIRN_HOME:-$HOME/.cairn}/plugins/$plugin_id"
mkdir -p "$plugin_root"
cp examples/bash-plugin/plugin.json "$plugin_root/plugin.json"
cp examples/bash-plugin/plugin.sh "$plugin_root/plugin.sh"
chmod 755 "$plugin_root/plugin.sh"
./scripts/cairnctl call plugins/reload '{}' --capability plugins.manage

Open Cairn’s command palette and choose Hello from Bash, or add the plugin’s Bash plugin status dock panel.

Download plugin.json · Download plugin.sh

Raw NDJSON

{"jsonrpc":"2.0","id":1,"method":"api/hello","params":{
  "token":"BASE64_TOKEN",
  "capabilities":["api.read","events.subscribe"]
}}
{"jsonrpc":"2.0","id":2,"method":"api/ping","params":{"nonce":"hello"}}

Plugin development rules

• Use a dedicated CAIRN_HOME while iterating so discovery, tokens, grants, and plugins stay isolated.
• Write diagnostics to stderr. Stdout is exclusively one JSON-RPC object per line.
• Return a response for every Cairn request ID, including activation and shutdown.
• Return JSON-RPC -32601 for unknown methods instead of exiting.