Blackmoon: Astrology software database conversion tooling

Jul 15

Blackmoon

Blackmoon is a utility to help Astrologers manage their astrological data. The flagship feature is migration between multiple platforms. So if you've been wanting to try out a new Astrology software but found it tedious or impractical to migrate your natal chart database, Blackmoon will help with that. If you have charts sprawled or duplicated across multiple formats and systems, you can now consolidate them into a single database or website.

This guide will help you perform some Blackmoon workflows. It is intentionally keyboard heavy with lots of "copypasta" to reduce mouse and typo caused errors.

Definitions

Spotlight - in macOS, tap ⌘ and space at the same time to bring up a generic search box called Spotlight
Terminal - in Spotlight, type terminal and hit enter.
Quit - ⌘-Q to completely close an application and all its windows
Command - commands are the strings of text which are typed or pasted inside the Terminal. I might switch between 'command', 'use', 'type', or 'paste' but in all cases these can safely be run by copying and pasting from this guide using ⌘-C, ⌘-V

Installation

We're going to install some prerequisites first. Install Homebrew for macOS, if you don't have it already.

Open Spotlight and launch a Terminal. Paste in the following:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

If you want to confirm that running this command is safe, go to brew.sh and take a look around. Google it, also, to get a vibe for the sentiment toward it across the broader internet. It is a popular and highly regarded package manager that gives macOS users access to a large ecosystem of software that would otherwise be outdated or only availble to Linux users.

If the installer asks for a password, it's the password you use when logging into your laptop. When homebrew is done installing, it gives instructions on how to make it both instantly and persistantly usable. All at once, select the 2 lines that begin with echo and the third line that begins with eval and copy paste them right there in that same terminal window.

Next, it's time to install Blackmoon.

brew install lucidaeon/tap/blackmoon

You'll see a bunch of information, but hopefully that includes a green checkmark and no errors.

Validation

Ensure that Blackmoon has been installed and runs well with the following command:

blackmoon --version

It should return with something like: Blackmoon 0.6.0

Backup

The command line can be unforgiving sometimes. It will do what you tell it to, not what you meant to do. Before proceding further, back up your natal chart database files, if that' what you're working with. Absolutely back. them. up.

copy to a flash drive
copy to a cloud drive
copy to a second computer
email them to yourself

If you want to write some of your local files TO one of the supported web platforms, ensure you backup the contents fo the web platform by importing the web platform contents to a local file format. See example 2 below. I recommend sfcht as it is quite stable and supports most of the data fields we care about.

Usage

Let's start using it.

Example 1 - Consolidation of SFcht file sprawl

Let's say your SFcht file collection is becoming unweildy. You can consolidate them like this -

blackmoon *.SFcht --quiet --output merged.sfcht

And the output will look like this:

$ blackmoon *.SFcht --quiet --output merged.sfcht
 in:         4115
 dupes:      1028
 out:        3087
wrote merged.sfcht

Omit "--quiet" if you want to see more details.

Example 2 - Backup or migration from website to local software

Make sure you've logged in to the web platform from one of your browsers recently, so Blackmoon can tailgate in on that recent authorization. There are other methods to gain authorization to web platforms. See blackmoon --help for details. Let's say you want to backup your web based charts to your local computer. You might run something like this -

blackmoon --quiet --from astrotheoros --grant-cookie-access --fill-house whole-sign --fill-zodiac tropical --fill-locus topocentric --output now.sfcht