Metadata-Version: 2.3
Name: taskee
Version: 0.1.0
Summary: Notifications for Earth Engine tasks.
Keywords: earth-engine,notifications,tasks,cli,command-line
Author: Aaron Zuspan
License: MIT License
         
         Copyright (c) 2026 Aaron Zuspan
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Requires-Dist: earthengine-api
Requires-Dist: rich
Requires-Dist: humanize
Requires-Dist: notify-py
Requires-Dist: requests
Requires-Dist: click
Requires-Dist: rich-click>=1.2.1
Requires-Dist: pydantic
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/aazuspan/taskee
Description-Content-Type: text/markdown

<img src="assets/logo.png" alt="taskee logo" style="width:180px;"/>

[![Earth Engine Python](https://img.shields.io/badge/Earth%20Engine%20API-Python-green)](https://developers.google.com/earth-engine/tutorials/community/intro-to-python-api)
[![PyPI version](https://badge.fury.io/py/taskee.svg)](https://badge.fury.io/py/taskee)
[![CI](https://github.com/aazuspan/taskee/actions/workflows/ci.yaml/badge.svg)](https://github.com/aazuspan/taskee/actions/workflows/ci.yaml)

`taskee` is a command-line tool for monitoring [Google Earth Engine](https://developers.google.com/earth-engine) tasks that can send notifications to your phone or computer to let you know when your tasks finish.

![](assets/dashboard.gif)

# Features

- 🔍 Monitor [Google Earth Engine](https://developers.google.com/earth-engine) tasks created with the Python API and/or the Javascript Code Editor
- 💻 Native notifications for Linux, Mac, and Windows
- :speech_balloon: Mobile push notifications for Android
- :tv: Built-in CLI dashboard

# Setup

```bash
pip install taskee
```

Run the setup steps below as needed.  
</br>

<details>
  <summary><b>Earth Engine</b> (required)</summary>
  Set up a <a href="https://developers.google.com/earth-engine">Google Earth Engine</a> account. If you haven't authenticated Earth Engine before, you'll be asked to do so the first time you run <code>taskee</code>.
  
</details></br>

<details>
  <summary><b>Pushbullet</b> (optional)</summary>
  If you want to receive mobile notifications (Android only), you'll need to create or connect an account with <a href="https://pushbullet.com">Pushbullet</a> and download the app on your device(s). Once Pushbullet is installed and you're logged in, go to your <a href="https://www.pushbullet.com/#settings">Account Settings</a>, create an Access Token, and copy the API key. The first time you run <code>taskee</code> with a <code>pushbullet</code> notifier, you'll need to enter your API key. That key will be stored locally so you don't have to enter it again.
</details></br>

<details>
  <summary><b>notify-send</b> (Linux only)</summary>
  Linux users may need to install <code>notify-send</code> to enable <code>native</code> notifications. If <code>taskee</code> is not working with the <code>native</code> notifier, run <code>sudo apt install libnotify-bin</code>.
</details>
</br>


# Usage

`taskee` offers a few different commands which you can see by running `taskee --help`.

```bash
Usage: taskee [OPTIONS] COMMAND [ARGS]...

  Monitor Earth Engine tasks and send notifications when they change states.

  Examples
      $ taskee test
      $ taskee tasks
      $ taskee log
      $ taskee dashboard failed completed -n pushbullet -i 0.5

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  dashboard  Show a live-updating dashboard.
  log        Log task events as they occur.
  tasks      Display a table of current Earth Engine tasks.
  test       Send test notifications.
```

## Running taskee

The `taskee dashboard` and `taskee log` commands initialize and run the notification system. They will continue running until you cancel them, periodically checking your Earth Engine tasks and sending you notifications.

### Choosing a Mode

There are two modes that `taskee` can run in: `dashboard` and `log`.

`dashboard` shows a live-updating dashboard that makes it easy to visually keep track of your tasks and events.

```bash
taskee dashboard
```

![A dashboard showing live-updating tasks and events](assets/dashboard.gif)

`log` is designed to be run in the background and prints minimal logs as events occur.

```bash
taskee log
```

![A terminal showing logs of new events.](assets/log.gif)

### Filtering Events

There are a lot of possible events that can happen to Earth Engine tasks. The list below describes the events recognized by `taskee`.

| Event | Description |
| ----: | :----- |
| *created* | :seedling: A new task is submitted. |
| *started* | :herb: A task starts processing. |
| *attempted* | :fallen_leaf: An attempt fails and the task is restarted. |
| *completed* | :evergreen_tree: A task finished successfully. |
| *failed* | :fire: A task fails to complete. |
| *cancelled* | :axe: The user cancels the task. |
| *error* | :exclamation: `taskee` crashes. |

By default, `taskee` will notify you of `errors` and `completed` or `failed` tasks, but you can specify which events to watch for by listing them when you launch `taskee`. For example:

```bash
taskee dashboard failed attempted cancelled error
```

You can also use `all` as a shortcut and `taskee` will notify you of all events.

```bash
taskee dashboard all
```

### Selecting Notifiers

By default, `taskee` will use the `native` notification system built into your computer's operating system. 

![](assets/notification_native_windows.gif)


If you want notifications on other devices, set up Pushbullet and then select it with the `-n --notifier` option.

```bash
taskee dashboard --notifier pushbullet
```

![](assets/notification_pushbullet.gif)

Like with events, you can use `all` as a shortcut and `taskee` will send both `native` and `pushbullet` notifications.

```bash
taskee dashboard -n all
```

### Other Options

You can set how often tasks are re-checked (in minutes) using the `-i --interval_mins` option. 

```bash
taskee dashboard -i 10
```

> **Warning**  
> `taskee` doesn't set a minimum interval, but if updates occur too frequently you may run into rate limits for Earth Engine or Pushbullet.

### Service Credentials

By default, `taskee` uses the persistent credentials stored on your local machine (whichever account you authenticated last). To use a [service account](https://developers.google.com/earth-engine/guides/service_account) instead, pass the relative path to your private key file using the `-k --private-key` option.

```bash
taskee dashboard -k path/to/private-key.json
```

### Example

Using what we learned above, let's set up `taskee` to start running in `log` mode, check for `cancelled` or `completed` task events, send us notifications using `pushbullet`, and update every `30` minutes.

```bash
taskee log cancelled completed -n pushbullet -i 30
```

## Other Commands

Aside from running the notification system, `taskee` has a few more commands that may be helpful.


### Task Summaries

The `tasks` command checks your Earth Engine tasks once, giving you a snapshot of your current tasks in a nice, readable table.

```bash
taskee tasks
```

![A table showing details for a list of tasks.](assets/tasks.png)

### Test Notifications

The `test` command sends a mock notification to any notifiers selected with the `-n --notifier` option. You can use this to make sure notifications are set up and working.

```bash
taskee test -n native
```

![](assets/test.gif)
