Creating an account and authenticating your ultralist cli

Note that if you create an account directly on ultralist.io, you'll still need to run ultralist auth to register your CLI with Ultralist Pro.

ultralist will create a directory - ~/.config/ultralist. In that directory, it stores 2 files:

creds.json - A token that ultralist will use to authenticate you

synced_lists.json - This is how ultralist knows if a list is synced.

You can always run ultralist check_auth to ensure you're properly authenticated.

Syncing a list

There are a couple of ways to sync a list, depending if that list already exists or not.

Creating a new list and setting it up to sync

Ensure you're authenticated via ultralist auth check.

Create the list via ultralist init

Ultralist will ask if you want to sync this list with ultralist.io. You can say y, and it will prompt you about which existing list you'd like to sync with, or to create a new list.

Select New list... and give it a name.

Presto, this new list is set up to sync with ultralist.io.

Syncing a list that exists locally, but not on ultralist.io

Ensure you're authenticated via ultralist auth check.

Run ultralist sync. ultralist will prompt you for the list's name.

Presto, this list is now set up to sync with ultralist.io.

Syncing a list that exists on ultralist.io, but not locally

Ensure you're authenticated via ultralist auth check.

In a directory that does not already have a .todos.json file, run ultralist init.

ultralist will ask you if you want to sync this list with ultralist.io. Enter y.

Choose the existing list you'd like to sync with.

Presto, the list will automatically be downloaded locally and will be set up to sync.

Pulling changes to a list on ultralist.io locally

If you have a synced list and changes were made to it on ultralist.io, you can pull those changes by running ultralist sync.

Opening the web view from ultralist

ultralist web will open up the list on ultralist.io.

How ultralist keeps lists in sync

ultralist sync has two roles for a synced list:

It pushes local changes to ultralist.io.

It pulls remote changes from ultralist.io.

For changes to your lists that you make locally, ultralist will automatically run sync in the background. If you're online, these changes will update the ultralist.io list immediately.

If you make changes on ultralist.io, you'll need to pull those changes locally. I have a cron task on my machine that will pull my synced lists every 15 minutes.

Offline first

Syncing is designed to be offline-first and stays out of the way. ultralist stores an event queue that it publishes to ultralist.io. The ultralist.io backend uses a reconciliation algorithm that will always keep lists correctly in sync.

The ultralist.io webapp uses the same event queue, and is also designed to run perfectly when offline.