Connections Command

The connections commands let an agent look up connectable services and ask for access to them — from inside a running heartbeat run. They are how an agent discovers "is there a connector for this service?" and then raises the intent to connect it, without leaving the terminal environment the runtime hands it.

paperclipai connections search "<query>"
paperclipai connections request <service>

Note: These commands only work during an active heartbeat run. They call runtime connection tools whose endpoints and token are injected into the run's environment (PAPERCLIP_RUNTIME_TOOLS_CONNECTIONS_SEARCH_URL, PAPERCLIP_RUNTIME_TOOLS_CONNECTION_REQUEST_URL, and PAPERCLIP_RUNTIME_TOOLS_TOKEN). Run them anywhere else and they stop with an error explaining they need the runtime connection environment from an active run.

Search for a connection

connections search looks up services or capabilities in the connections catalog. The query is optional — omit it to browse.

paperclipai connections search "google calendar"
paperclipai connections search github
paperclipai connections search

The result is written to stdout as JSON. Without --json it is compact single-line JSON; with --json it is pretty-printed.

Request a connection

connections request raises a connection request for a specific service, identified by its slug — the kind of value connections search returns.

paperclipai connections request google-calendar
paperclipai connections request github --json

Like search, the response prints to stdout as JSON, pretty-printed when you pass --json.

Tip: Search first, request second. Take the service slug from a search result and feed it straight into request so you are asking for a service the catalog actually knows about.

See also

• Run Commands — the heartbeat runs whose environment makes these commands work.
• Adapter Commands — the runtimes that execute agent work server-side.
• Output and Scripting — working with the JSON these commands emit.