Setting up

The NOLGIA plugin for a desktop app connects the app on your computer to NOLGIA. Once it is signed in and Connected is on, you, NOLGIA Agent or any agent holding your token can send it commands: read what is open, run code in the app's own scripting language, render a preview, import a file from your NOLGIA library, export, save, open, and for some apps run the DIT or transcribe clips. The plugin runs each command on your computer and posts the result back.

• Install a plugin from nolgia.ai/plugins: Blender, After Effects, Premiere Pro and Illustrator (one extension for all three), Photoshop, DaVinci Resolve Studio.
• Only your own credentials see your apps and send them commands. NOLGIA Agent reaches an app only while that app's Allow NOLGIA Agent switch is on.
• Commands are free. They cost no credits; generations you make along the way are priced as usual.
• With NOLGIA's MCP server, the same commands are the nolgia_app_* tools (MCP). This page is the REST API underneath them.

Use the plugin, never outside scripting #

Send every command through the NOLGIA plugin. Never drive the app from outside it: no AppleScript or osascript, no COM, no Windows UI automation, no simulated keystrokes or clicks, no second copy of Blender run from a terminal on the person's file, and no DaVinciResolveScript from a terminal.

The plugin is what keeps the person in control and their work safe. It lists every command in its Activity list, waits for their approval when Ask before running code is on, runs code inside one undo step where the app has one, holds back the app's own dialogs where the app allows it so nothing waits for a click, catches every script error and hands it back as text with the failing line. A command sent from outside skips all of that, and a bad call that way can crash the app and lose unsaved work: in testing, one malformed AppleScript command sent straight to After Effects crashed it.

The endpoints #

POST /bridge/sessions, GET /bridge/sessions/{id}/next and POST /bridge/commands/{id}/result are what the plugin itself calls; DELETE /bridge/sessions/{id} is the plugin switching off. You use the others.

1. Find the app #

GET /bridge/sessions lists the apps connected right now, most recently seen first. A session is live while its plugin has checked in within the last 60 seconds.

curl -s https://api.nolgia.ai/v1/bridge/sessions -H "Authorization: Bearer $NOLGIA_TOKEN"
# or, with the nolgia CLI:
nolgia api GET /bridge/sessions

An empty list means no app is connected: install the plugin, sign in and turn on Connected. capabilities lists the command kinds that plugin runs; info and run are always there.

2. Send a command #

POST /bridge/commands queues a command for one app. Without session_id it goes to the app's most recently seen live session; pass session_id when two windows of the same app are connected.

curl -s https://api.nolgia.ai/v1/bridge/commands \
  -H "Authorization: Bearer $NOLGIA_TOKEN" -H "Content-Type: application/json" \
  -d '{"app": "blender", "kind": "run", "args": {"language": "python", "code": "import bpy\nresult = [o.name for o in bpy.data.objects]"}}'
# or: nolgia api POST /bridge/commands --body @command.json

The answer is the command, 201 and queued. Refusals carry a code:

args is at most 256 KB as JSON. timeout_seconds (5 to 900, default 120) sets expires_at: give a command that waits for the person's approval, a long render or a DIT offload more time.

3. Read the result #

GET /bridge/commands/{id}?wait=25 holds the request until the command finishes or 25 seconds pass, then answers with the command as it is. Ask again until status is no longer queued or running.

while :; do
  cmd=$(nolgia api GET /bridge/commands/$ID --query wait=25)
  status=$(printf '%s' "$cmd" | python3 -c 'import json,sys; print(json.load(sys.stdin)["status"])')
  case "$status" in queued|running) ;; *) printf '%s\n' "$cmd"; break ;; esac
done

POST /bridge/commands/{id}/cancel cancels a queued or running command. The app may already have made changes; cancelling does not undo them. GET /bridge/commands lists recent commands (never their args, because a run carries code).

Command kinds #

A plugin checks args before it runs anything and answers a wrong one with an error that names the right choices. GET /desktop-apps/{app}/rules serves the rules every NOLGIA workflow in that app follows (safety copies, keeping work editable, previews, the scripting traps), and they apply to your own commands just as well.

Code in each app #

run carries code in the app's own language. Set result to hand data back; the plugin returns {value, stdout, stderr}, and on failure the error with the line that failed.

Code cannot be stopped from outside once it runs: after timeout_seconds the plugin stops waiting and says so, and a loop that never ends keeps the app busy until it does. Keep each run to one small step.

The person's approval #

Some commands wait in the plugin for the person to click before they run. While they wait the command is running.

• Ask before running code, a switch in the plugin: every run shows its code first and waits for Run code or Deny.
• DIT writes always wait, whatever that switch says: an offload (Copy and verify), a rename with apply (Rename files) and an undo (Restore names). A dry run, a verify, an inventory and a report do not.
• Opening over unsaved changes in Blender waits too.

A Deny ends the command as failed with an error such as "The person at After Effects clicked Deny, so this did not run." No answer before expires_at ends it as failed with "Nobody approved this in After Effects in time, so it did not run." Tell the person to look at the NOLGIA panel before you send a command that waits, give it a long timeout_seconds, and never send it again on your own after a Deny.

One example per app #

Each body below goes to POST /bridge/commands.

Blender, the objects in the scene:

{"app": "blender", "kind": "run", "args": {"code": "import bpy\nresult = [(o.name, o.type) for o in bpy.context.scene.objects]"}}

After Effects, the comp in the viewer:

{"app": "after_effects", "kind": "run", "args": {"code": "var c = app.project.activeItem;\nresult = (c && c instanceof CompItem) ? {name: c.name, layers: c.numLayers, fps: c.frameRate} : null;"}}

Premiere Pro, the sequences in the project:

{"app": "premiere", "kind": "run", "args": {"code": "var out = [];\nfor (var i = 0; i < app.project.sequences.numSequences; i++) out.push(app.project.sequences[i].name);\nresult = out;"}}

Illustrator, the open document and its artboards:

{"app": "illustrator", "kind": "run", "args": {"code": "result = app.documents.length ? {name: app.activeDocument.name, artboards: app.activeDocument.artboards.length} : null;"}}

Photoshop, the layers of the active document:

{"app": "photoshop", "kind": "run", "args": {"code": "result = doc ? doc.layers.map(l => ({ id: l.id, name: l.name, visible: l.visible })) : null;"}}

DaVinci Resolve Studio, the project and its current timeline:

{"app": "resolve", "kind": "run", "args": {"code": "result = {'project': project.GetName(), 'timeline': timeline.GetName() if timeline else None}"}}

A preview of the Blender scene at frame 1:

{"app": "blender", "kind": "preview", "args": {"frame": 1, "width": 768}}

A DIT plan in Premiere Pro, one path per card, nothing copied:

{"app": "premiere", "kind": "dit", "args": {"action": "start", "subcommand": "offload", "sources": ["/Volumes/A001", "/Volumes/B001"], "destinations": ["/Volumes/RAID/Shoots", "/Volumes/Shuttle"], "shoot": "TEST", "dry_run": true}, "timeout_seconds": 300}

The offload itself is the same body without dry_run: it waits for Copy and verify in the panel and hands back a job_id to follow with "action": "status".