Skip to content
ActionsDotWork logo ActionsDotWork. Docs
Home

› URL Scheme (x-callback-url)

Since v2025.2, BarCuts supports the x-callback-url standard to query for workflows. This is useful if you want to create a custom launcher for BarCuts, or if you want to use its list of active/ global workflows in scripts (see terminology).

The available endpoint is barcuts://workflows. It returns a data parameter to the x-success URL, holding a (URL-encoded) JSON string, which contains an object.

Return value format

The returned data structure is a Javascript object, for example:

{
  activeAppID: 'com.mitchellh.ghostty',
  activeAppName: 'Ghostty',
  activeWorkflows: [
    {
      fullTitle: 'Workflow 1',
      workflowID: '17620440-E9E8-4B5C-9C7A-9B60C24DD428'
    }
  ],
  globalWorkflows: [
    {
      fullTitle: 'Workflow 2',
      workflowID: '642957AB-6EDF-4CEA-B1C4-753897F984AA'
    },
    {
      fullTitle: 'Sub menu ≫ Workflow 3',
      workflowID: 'ADB4BEDC-720B-4DB2-89E3-10D464E7F5D3'
    }
  ]
}

The keys:

  • activeAppID (string) is the bundle ID of the currently active app
  • activeAppName (string) is the name of the currently active app
  • activeWorkflows and globalWorkflows are arrays each containing workflow sets, i.e. objects with both fullTitle and workflowID keys.

These "workflow sets" are sorted alphabetically by fullTitle. If a tagged workflow is configured to show in a sub menu, fullTitle will contain both the name of the sub menu and the workflow title, separated by "≫". workflowID is the UUID which can be used to call the workflow.

A condensed x-callback-url intro

You can query BarCuts via a barcuts://… URL for information about its workflows, specify a return address in a URL parameter, and BarCuts will call that address with the results.

An example:

barcuts://workflows
  ?x-success=my-app%3A%2F%2Fsuccess
  &x-error=my-app%3A%2F%2Ffailure

This example call, formatted for better readability, contains two parameters:

  • x-success contains a base URL for returning success information – in the above example, that's my-app://success
  • x-error contains a base URL for returning failure information – in the above example, that's my-app://failure.

When BarCuts has completed the work requested by the incoming call, it'll build a callback URL from the value of either x-success or x-error. When it was successful, it'll call the success URL, adding a URL parameter list containing the requested data as a JSON string.

Let's say you requested the list of workflows for the currently active app, and BarCuts returns the example data used in the Return value format section above. The return URL called by BarCuts would be:

my-app://success?data=%7B%22activeAppID%22%3A%22com.mitchellh.ghostty%22%2C%22activeAppName%22%3A%22Ghostty%22%2C%22activeWorkflows%22%3A%5B%7B%22fullTitle%22%3A%22Workflow%201%22%2C%22workflowID%22%3A%2217620440-E9E8-4B5C-9C7A-9B60C24DD428%22%7D%5D%2C%22globalWorkflows%22%3A%5B%7B%22fullTitle%22%3A%22Workflow%202%22%2C%22workflowID%22%3A%22642957AB-6EDF-4CEA-B1C4-753897F984AA%22%7D%2C%7B%22fullTitle%22%3A%22Sub%20menu%20%E2%89%AB%20Workflow%203%22%2C%22workflowID%22%3A%22ADB4BEDC-720B-4DB2-89E3-10D464E7F5D3%22%7D%5D%7D

For more details, visit the x-callback-url website.

Good to know

Be aware that calling the URL scheme will by default focus BarCuts (because that's how macOS works), meaning it'll return your tagged workflows for BarCuts itself (because at that point, it's the active app). To prevent that, call the URL scheme in the background, e.g. from the shell:

Terminal window
# 👍🏼 This will trigger a background call, and keep the currently active app focussed
open -g "barcuts://workflows?x-success=my-app%3A%2F%2Fsuccess&x-error=my-app%3A%2F%2Ffailure"


# 👎🏼 This will trigger a foreground call, and temporarily focus BarCuts
open "barcuts://workflows?x-success=my-app%3A%2F%2Fsuccess&x-error=my-app%3A%2F%2Ffailure"

But why?

Because scripting is great, automation is great, open formats are great! Because your tools shouldn't restrict you, you should be able to use the data they hold for you however you want.

For example, you could use this URL scheme to create your own custom launcher for BarCuts. Fetch the list of active workflows, select one, use the macOS-native /usr/bin/shortcuts CLI command to run it. Just an idea. Or wire it up to Alfred or Raycast, and trigger your active Shortcuts right from there.

Let me know if you built something cool with it, I would love to see it! If it's a good fit, I might even add a link here. 🤙🏼