URL Scheme - beorg

If you use apps such as Shortcuts or Drafts then you may find the beorg URL scheme useful. The URL scheme allows you to launch the beorg app and do one of the following:

Add a new item to a file
View the agenda
View the tasks tab, optionally showing the results of a search
View a specific file
Search for items and return the results as a JSON dictionary, new in beorg 2.12.0

beorg supports x-success and x-cancel arguments, however they are not mandatory.

Adding a new item

To add a new item you need to use the URL beorg://x-callback-url/capture. Without any arguments the quick capture dialog will be shown. You can also supply the following arguments:

Parameter	Description	Example
`title`	The item headline	Shopping List
`notes`	Notes to add to the item	Buy eggs
`scheduled`	Schedule the item using a date in the format `yyyy-MM-dd`	2018-09-18
`deadline`	Set the item deadline using a date in the format `yyyy-MM-dd`	2018-09-18
`file`	The name of the file, without an extension, to add the item to	journal
`template`	Name of a template to apply	Daily Review
`edit`	Whether or not the user can edit the item before it is created	true

For example beorg://x-callback-url/capture?title=New%20task&notes=Buy%20eggs&scheduled=2017-10-03&file=shopping

If a template is supplied then only the URL scheme parameters title, notes and file are taken into account.

Show the agenda

To view the agenda use the URL beorg://x-callback-url/agenda.

Show the tasks tab

To view the tasks tab use the URL beorg://x-callback-url/tasks.

If you would like to view the results of a search then provide the argument search with the value being the search string, using the same syntax you would use in the UI. For example:

beorg://x-callback-url/tasks?search=t%20bookmark

In the above example the search t bookmark has URL encoded the space so that the parameter becomes t%20bookmark.

View a file

To view a file use the URL beorg://x-callback-url/file with the argument file, for example beorg://x-callback-url/file?file=shopping

Search for items

To search for items in beorg there is the URL beorg://x-callback-url/search?search=<SEARCH STRING>. The search string is the same as can be entered into the search control on the Agenda and TODO tabs. You will need to ensure that this is URL encoded.

The URL supplied in the x-success argument will be called with the additional parameter json. This will contain a dictionary with the attributes count, the number of search results, and items, the search results. Each search result is as follows:

Attribute	Description	Example
`title`	The headline of an item	Buy eggs
`notes`	Any accompanying notes	Get 6 large free range eggs
`state`	TODO state	DONE
`priority`	The item priority, if available	B
`tags`	A list of any tags assigned to item	Shopping,Groceries
`scheduled`	The scheduled date and time in ISO-8601 format	2020-01-15T09:00:00Z
`deadline`	The deadline date and time in ISO-8601 format	2020-01-15T09:00:00Z
`date`	The show on or active date and time in ISO-8601 format	2020-01-15T09:00:00Z

The search callback is most useful with the Shortcuts app as part of a larger workflow, and is only available in 2.12.0 and above.