Open a session from a link

A syntic-cli:// link opens Syntic Code in a terminal with a prompt already typed in. Put one in a runbook, a README, an alert or a chat message, and whoever clicks it lands in a session ready to start the task. Nothing runs until they read the prompt and press Enter.

syntic-cli://open?q=Investigate%20the%20spike%20in%20checkout%20errors%20since%2014%3A00

How it works

Someone clicks a syntic-cli:// link in a browser, chat app or document.
The operating system hands the link to the syntic program it has registered for that scheme.
Syntic Code checks the link strictly. Anything it does not recognize is refused.
If the click did not come from a terminal, Syntic Code opens a new terminal window and starts there.
The interactive session starts with the prompt box filled in. The person reviews it, edits it if they like, and presses Enter to send.

Links never send a prompt, run a command or change a setting on their own.

Link types

Link	Fills the prompt box with
`syntic-cli://open`	Nothing; just opens a session.
`syntic-cli://open?q=<text>`	`<text>`, URL-decoded.
`syntic-cli://install-plugin/<plugin>@<marketplace>`	The `/plugin install` command for that plugin.
`syntic-cli://add-marketplace/<source>`	The `/plugin marketplace add` command for that source.

The plugin links still leave the final step to the person: they see the command and confirm it like any other plugin install (Install plugins).

Build a link

Take the prompt text and URL-encode it into the q parameter. Spaces can be %20 or +; line breaks are allowed as %0A.

python3 -c 'import urllib.parse,sys; print("syntic-cli://open?q=" + urllib.parse.quote(sys.argv[1]))' \
  "Read the last 200 lines of /var/log/app/error.log and summarize the errors"

Rules a link must follow

Rule	Why
Only the `syntic-cli://` scheme, and only the actions above	Unknown actions are refused, never guessed.
At most 4,096 characters	Longer links are refused.
No control characters, except line breaks inside the prompt	They could be used to smuggle extra arguments.
Plugin and marketplace names must not contain path separators or `..` once decoded	A link cannot reach outside its slot.

A link that breaks a rule is refused with a message; nothing else happens.

Examples

In a runbook

## High error rate on the payments API
 
1. Check the dashboard for the affected region.
2. [Open a triage session](syntic-cli://open?q=Payments%20API%20error%20rate%20is%20high.%20Check%20recent%20deploys%20with%20git%20log%2C%20read%20the%20error%20logs%2C%20and%20propose%20a%20rollback%20or%20fix.)
3. Page the on-call lead if the rollback is needed.

Most Markdown viewers make links with custom schemes clickable. Some (and some chat apps) only show them as text; in that case paste the link into a browser, or pass it to syntic --handle-uri in a terminal.

From the shell

# macOS
open "syntic-cli://open?q=Review%20the%20diff%20on%20this%20branch"
 
# Linux
xdg-open "syntic-cli://open?q=Review%20the%20diff%20on%20this%20branch"

You can also skip the operating system and pass the link straight to the program:

syntic --handle-uri "syntic-cli://open?q=Review%20the%20diff%20on%20this%20branch"

syntic-cli://install-plugin/release-tools@team-marketplace

Registration and platforms

Syntic Code registers itself as the handler for syntic-cli:// the first time it starts interactively, and again if the program moves. No administrator rights are needed.

Platform	How the handler is registered	New terminal opened with
Linux	A hidden desktop entry in `~/.local/share/applications` (or `$XDG_DATA_HOME/applications`), set as the default handler with `xdg-mime`.	`x-terminal-emulator`
Windows	A key under `HKCU\Software\Classes\syntic-cli` in your own part of the registry.	A new console window
macOS	Not registered automatically: a link scheme needs an application bundle on macOS. Use `syntic --handle-uri "<link>"` from a terminal.	Terminal

Where the session starts

A session opened from a link starts in the folder the new terminal window opens in, usually your home folder. Mention the project in the prompt, or move the session with /cd <path> before sending. When you run syntic --handle-uri yourself from a terminal, the session starts in that terminal’s current folder.

Turn links off

Setting	Effect
`"disableDeepLinks": true`	Links are not handled, and the handler is not registered.
`"disableDeepLinkRegistration": true`	Syntic Code does not register itself as the handler. On Linux, an existing entry is removed. Running `syntic --handle-uri` by hand still works.

Either key can be set in any settings file.

Troubleshooting

Problem	What to do
Clicking the link does nothing	Start `syntic` once interactively so it registers itself. On macOS, use `syntic --handle-uri` instead.
`xdg-open` is not found on Linux	Install your desktop’s `xdg-utils` package, or use `syntic --handle-uri`.
The link shows as plain text	The app does not allow custom schemes. Copy the link into a browser address bar or a terminal.
The session opens in the wrong folder	It opens where the new terminal starts. Use `/cd` before sending, or open the link with `syntic --handle-uri` from the project folder.
The link is refused	Check it against the rules above. A common cause is an unencoded character or a link over 4,096 characters.
The wrong terminal app opens on Linux	The system’s `x-terminal-emulator` choice decides. Change it with your distribution’s alternatives tool.

Channels Overview