The ChurchTools-CLI-Tool provides direct data access to your ChurchTools application instance. Interaction is via easy to learn commands in a CLI application (cmd on windows, terminal on mac, bash on linux). The focus is on:
- 🔍 the display of data
- 📃 the export of data
- 📈 the creation of reports
- 🔨 the migration and import of data
Support: If there is a functionality or command that you are missing, feel free to email me with your requirements. The implementation usually takes place in less than 3 days: lukas.dumberger@gmail.com
This Demo shows how to export all songs from ChurchTools with the CLI-Tool:
To use this CLI-Tool you need to install PHP 8.0 on your System. For the CLI tool to function correctly and send HTTP requests, it is necessary to activate the curl extension in the php.ini configuration file.
- Tutorial: Install PHP on Windows
- Tutorial: Install PHP on Mac
Option 1: Download phar
Download the packed phar executable: ct.phar
Execute the phar from your bash/cmd and e.q. list all available commands:
php ct.phar listOption 2: Clone this repo
Clone this repo and execute the CLI from your bash/cmd and e.q. with this command to print all available commands:
php ct listBefore you can retrieve data from ChurchTools, you must set up the configuration. Call this command:
php ct.phar settings:setup
Retrieve date from ChurchTools with the show-commands. For example show all available calendars:
Other available commands:
show:api-tokenshow:absence(options:--start-date,--end-date)show:calendarsshow:groups(option:--my-groups)show:group-membersshow:resourcesshow:bookings(options:--start-date,--end-date)show:events(options:--my-events,--start-date,--end-date)show:services(option:--service-group-ids)show:songs(options:--name,--should-practice)show-song-categories
Options:
--helpget additional context--exportexport the displayed table to an excel file--export-jsonexport the displayed table to an json-file--export-json-objectsexport the displayed models as raw json-objects to an json-file--add-template=[TEMPLATE_NAME]create template from command (see section Templates)
Export data to excel files with the export-commands. For example the export:song-usage-command:
Options:
--helpget additional context--add-template=[TEMPLATE_NAME]create template from command (see section Templates)
Loads event (e.q. 281) and retrieve all songs that are linked in the event agenda. Then downloads all file-attachments of the selected arrangement in the right order.
php ct.phar export:event-setlist 281php ct.phar export:song-usage 42 --start_date=2019-02-01 --end_date=2020-04-01Export Usage of songs of all events that are created in the calendar with the id 42. You can optional add start- / end-date flags.
php ct.phar export:service-person 42 12,13,14 --start_date=2019-02-01 --end_date=2020-04-01Export the services of all events that are created in the calendar with the id 42. You can optional add start- / end-date flags.
php ct.phar export:permissionsDetailed information: Export-Permission
php ct.phar export:person-tags 11,18,16Export the Tags of all Group-Members in the given groups. In the example above the export will retrieve all members from group 11, 18 and 16.
Export the images of all accessible groups. The images will be stored in a separate folder:
php ct.phar export:group-imagesExport only images of groups i am member of:
php ct.phar export:group-images --my-groupsExport the avatars of all group members and store them to a local folder. Pass as argument the group-ids you want to export the avatar-images from.
php ct.phar export:group-member-avatars 1192,2921Templates are useful to store frequently executed commands. With the option --add-template=[TEMPLATE-NAME] you can
store the command with all arguments and options to a template:
With the template:list command you can display all stored templates. To execute a template simply call template:run
with the template-name as argument.
template:listlist all stored export-templatetepmlate:runrun a stored export-templatetemplate:deletedelete a stored export-templatetemplate:cleardeletes all templates
With the CLI tool you can also update (or migrate) data. The migrate-commands are available for this purpose:
php ct.phar migrate:song-arrangement-bpmphp ct.phar migrate:song-arrangement-namesphp ct.phar migrate:song-should-practice-clearphp ct.phar migrate:group-member-hierarchy
IMPORTANT: By default all migrate commands run in "Test-Mode". This means the data is not really changed. It only simulates the commands to give you the opportunity to check if the migration updates the data correctly. To run the migration on production-data please add the option --no-testmode.
Options:
--add-template=TemplateNamecreate Template for Migration--testmoderun migration in testmode (this is default case)--no-testmoderun migration on production data--silencedont print migration results to cli-console--song-categories(only for song-migrations) filter by song-categories as id-list
Example on how to use migrations:
Reports generate Markdown files as output. There is currently one report available:
This reports needs two arguments:
- parent-group-id
- children-group-ids (as comma-seperated list)
The report processes all child-groups and checks if all members of a child-group are also member of the parent group. Also it checks is all members of a parent group are in at least one child-group.
The output of the report can look like this:
The report displays the hierarchy of this group as list. It need a group-id as argument.
Example output:
# Group-Hierarchy Report
## Group:
- ID: 1141
- GUID: [GUID]
- Name: 5pm: WORSHIP & PRODUCTION
## Children-Groups:
- 5pm: WORSHIP & PRODUCTION (#1141)
- 5pm: PRODUCTION (#1156)
- 5pm: PRODUCTION - Sound (#1838)
- 5pm: PRODUCTION - Light (#1841)
- 5pm: PRODUCTION - Visualisation (#1844)
- 5pm: WORSHIP Musiker Pool (#1469)
- 5pm: W&P Leitungsteam (#1825)
## Parent-Groups:
- 5pm: WORSHIP & PRODUCTION (#1141)
- 5pm: KERNTEAM (#1138)You can list, update and edit the settings:
settings:clearremove all settingssettings:listlist all available settingssettings:setupsetup settings interactive