Commands

Tranquil adds a few helper commands for automations to the command palette (Cmd-Shift-P). They’re shortcuts for common steps: running the script you’re editing, checking it before it touches a form, showing its output, and managing the scripts you’ve registered and the permissions you’ve approved.

There are three kinds:

• SDK commands are built in. They work on the script in the active editor, or on the page in the active browser tab. Type “SDK” to list them.
• Debug commands start, step through and stop a debug session, and set breakpoints. Type “Debug” to list them.
• Automation commands are your own scripts, each registered as a one-step command that runs it from anywhere. Type “Automation:” to list them.

SDK commands

The built-in commands, for running, checking and managing scripts. Two of them also have a keyboard shortcut.

Command	Key (macOS)	What it does
SDK: Run Automation	Cmd-Shift-R	Runs the script in the active editor, or only its selected lines (Running Automations)
SDK: Toggle Runs Panel	Cmd-Shift-U	Shows or closes the Automation Runs panel (Watch your runs)
SDK: Register Current File		Adds an automation command that runs the script in the active editor
SDK: Unregister Current File		Removes the script’s automation command; the file is untouched
SDK: Check Custom Parts		Runs the script with its page actions held back, checking each target and the parts a dropdown needs (Testing)
SDK: Map Custom Parts		Drafts a custom parts map for the form in the active browser tab (Custom Parts)
SDK: Revoke All Permissions		Forgets every approval, so each script asks again on its next run (Permissions)

SDK command details

• Run Automation and Check Custom Parts need a saved .ts file in the active editor. A selection runs on its own, with the file’s import lines; part of a block is refused. A script’s first run asks you to approve its @permissions header.
• From a browser tab, Cmd-Shift-R is the browser’s hard reload; the palette command runs the last script editor you used.
• Map Custom Parts needs the form’s dropdowns filled in first: a field shows where it keeps its value only once it has one. It’s a built-in script that may only read pages (@permissions tabs), and it opens the draft in a new editor.
• Toggle Runs Panel closes only the panel; the rest of the bottom dock stays open.
• Revoke All Permissions asks for no confirmation, since it can only make Tranquil ask more.

Debug commands

The debugger’s commands work on the .ts script in the active editor and the debug session it starts. How to use them: Debug Automations.

Command	Key	What it does
Debug: Debug Automation		Starts a session for the script in the active editor. It starts paused and runs to your first breakpoint; it always runs the whole file
Debug: Toggle Breakpoint	F9	Adds or removes a breakpoint on the cursor’s line
Debug: Clear All Breakpoints		Removes every breakpoint, in every file
Debug: Continue	F5	Runs on to the next breakpoint
Debug: Step Over	F10	Runs the next line, without going into the functions it calls
Debug: Step Into	F11	Goes into the function being called
Debug: Step Out	Shift-F11	Finishes the current function and stops at its caller
Debug: Stop		Ends the session and stops the script’s process
Debug: Toggle Debug Panel		Shows or hides the debug pane in the left dock

Debug command details

• The keys work only while an editor has focus. A browser tab keeps F5 to reload and F12 for its own DevTools. On Windows and Linux, F11 steps into instead of toggling full screen while an editor has focus.
• Toggle Breakpoint and Clear All Breakpoints are in the palette only while an editor has focus.
• Continue, the steps and Stop do nothing when no session is running.

Automation commands

An automation command runs one script you’ve registered, without opening it first. The palette has one for each script you’ve registered with SDK: Register Current File, and none until you register one. Each is named from its file: count-paragraphs.ts becomes Automation: Count Paragraphs.

What an automation command does differently from Run Automation:

	Run Automation	Automation command
Runs	the script in the active editor	the registered file, wherever focus is
What it runs	the file as saved, or only the selected lines (as they are in the editor)	always the whole file as saved
Runs panel label	manual	the command’s name, for example “Count Paragraphs”
context.trigger	{ kind: "manual" }	{ kind: "command", name: "Count Paragraphs" }

Neither saves the file first, so save before running. Both ask for approval the same way, act on the same browser tab (the last one you viewed), and show in the Automation Runs panel. A script can read context.trigger to tell how it was started (Tranquil API).

• Register and Unregister say what they did in a notification (“Registered: Automation: Count Paragraphs”, “Already registered: …”, “Unregistered: …”), or why nothing changed (“Active file is not a .ts automation”, “File is not registered”).
• Registered commands load at every start, from the registeredAutomations list under "tranquil-automations" in ~/.tranquil/config.cson. Each entry holds the command’s name and the file’s path.
• A moved or deleted file isn’t found. Its command stays in the palette, and running it fails with “Cannot read automation”, recorded in the Runs panel. Unregister needs the file open at its old path, so for a file that’s gone, delete its entry from config.cson instead.
• Two files with the same name in different folders get two commands with the same name. Name files for what they do.
• To rename a command, edit its name in config.cson and reload the window. Or unregister the file, rename it, and register it again; unregister first, since it finds the command by the file’s current path.

Bind a key to one

Each automation command has a command id made from its file’s path, with every run of characters other than letters, digits and _ replaced by -: /Users/you/scripts/count-paragraphs.ts is tranquil-automations:automation--Users-you-scripts-count-paragraphs-ts. Bind a key to it in ~/.tranquil/keymap.cson:

'atom-workspace':
  'ctrl-alt-1': 'tranquil-automations:automation--Users-you-scripts-count-paragraphs-ts'

Moving the file changes the id, so the binding needs updating too.