Introducing Fiss (Fiss)

Up a Level

In a world where there are a lot of tools to manage tasks, this is one more. Fiss is a CLI-based tool that exposes issues from forges (such as Foregejo[1]) in a task-centric interface. This tool is inspired by Taskwarrior[2] and is designed from the ground up with the intent of using multiple forges, groups/organizations, and projects as the high-level organization.

1: https://forgejo.org/

2: https://taskwarrior.org/

Justification

There are a lot of tools that do the same thing, managing tasks. As well-designed or powerful as they are, the main reason for writing Fiss is that they didn't work the way we needed them too.

There Is More Than One Way To Do It

— Larry Wall

Fiss does, but isn't to say we haven't tried to find another alternative. We have, for many years and many attempts to find the “one perfect tool” for us.

Taskwarrior

Taskwarrior is very powerful, but it doesn't work well outside of the CLI. In our experience, the web services for sharing tasks across machines work fairly well, but are cumbersome to set up.

The support on Android, our current phone operating system, is relatively poor.

In many cases, the other services end up packaging Taskwarrior inside them to perform the various calculations because Taskwarrior is also very complex and not well documented. At least, it seems that way since there are not many Taskwarrior-compatible alternatives. Even the Android packages we found effectively said they packaged Taskwarrior inside them.

iCalendar

We love iCalendar (`.ics`) files. With our local NextCloud[3] server, it is great for handling a lot of our common tasks.

3: https://nextcloud.com/

Working with a Linux CLI and `.ics` is difficult. We've tried a number of different ways over the years and haven't found anything that works the way we want. Or consistently.

Introduction

Right now, this tool is barely alpha. It requires a lot of manual editing of the configuration file as documented on the website[4].

4: //mfgames.com/fiss/

Adding a Server

Adding a server is pretty simple. A server has a short name, which is used by the tabular output and to reference the server.

export FISS_SERVER=mfgames
export SERVER_URL=https://src.mfgames.com
#TOKEN=the token from Forgejo
fiss server add -s $FISS_SERVER --url $SERVER_URL --token $TOKEN
fiss server add --url $SERVER_URL --token $TOKEN

It will also automatically pick up `FISS_SERVER` from the environment. Same for `FISS_GROUP` and `FISS_PROJECT` below.)

export FISS_SERVER=mfgames
fiss server add --url $SERVER_URL --token $TOKEN

It can be listed, not that it helps much.

$ fiss server list
 server   url                             forge    updated_seconds
 mfgames  https://src.mfgames.com/        forgejo  2025-02-15 13:15:41

All lists can be dumped as JSON:

$ fiss server list --json | jq
[
  {
    "server": "mfgames",
    "url": "https://src.mfgames.com/",
    "forge": "forgejo",
    "updated_seconds": "2025-02-14 18:04:54"
  }
]

They can also be dumped as Markdown:

$ fiss server list --markdown

| server  | url                      | forge   | updated_seconds     |
|---------|--------------------------|---------|---------------------|
| mfgames | https://src.mfgames.com/ | forgejo | 2025-02-14 18:04:54 |

The reason servers are considered first-class is that we wrote Fiss to handle multiple forges at the same time. We have multiple Forgejo instances. Eventually, this tool will be expanded to also include iCalendar, SourceHut, GitLab, and GitHub. Potentially, one could have multiples of those also, so servers are part of the organization structure.

Groups

On a server, you have groups. Right now, users don't work yet, but groups are fine.

$ export FISS_GROUP=fiss
$ fiss group add -s $FISS_SERVER -g $FISS_GROUP

We decided to call the organizations and users “groups” because our “day job” uses “organizations” and it is really hard to spell that consistently while typing at speed. Using “groups” is relatively generic and is sufficient for our needs.

Projects

Projects are the third level of organization. Creatively, they are done the same way.

$ FISS_PROJECT=fiss
$ fiss project add -s $FISS_SERVER -g $FISS_GROUP -p $FISS_PROJECT

Caching

To avoid overloading the forges, we cache the issues. In the future, we periodically will refresh the data, pick up new issues, close others. Right now, you have to manually pull in the data.

fiss cache sync

⚠ Since there isn't a lot of elegance at this point, this will pick up all projects underneath a group and also download every single issue from those projects. That includes closed and open. So, it would not be a good idea to point this at any project that has a large number of issues.

There is also going to be controls for automatically subscribing to new projects, so you can choose to get all of them, or only require specific ones.

Issues

Once everything is synced, then the commands are pretty simple. To list issues:

fiss list -s $FISS_SERVER -g $FISS_GROUP -p $FISS_PROJECT

If the command is run inside a Git repository (any inner directory can work, it will find the Git root), it will attempt to pick up the server, group, and project from the remotes. Also, if there is a distinct name for a project, then `-p $FISS_PROJECT` would be sufficient.

If you want to list all projects inside a Git repository, the `list` command supports globbing for servers, groups, and slugs. This means `fiss list -p '*'` will show all projects no matter where you are in your directory structure. Also, multiple globbing can be done with colons, such `fiss list -p fiss:mfgames-cil` will list all `fiss` and `mfgames-cil` projects.

From this point on, we're going to assume you are in the Git directory or have `FISS_SERVER`, `FISS_GROUP`, and `FISS_PROJECT` set appropriately.

fiss list

Creating a new issue also relatively simple and there really isn't that much. The rest of the commands are assuming you are in a Git directory, or you exported

$ fiss add -t "Name of project"

This creates an issue. Right now, it just says nothing but it will eventually give you a useful message or at least emit the issue number.

There are commands to open and close tickets using `-i` or `--issue` with the issue number.

fiss issue close -i 3
fiss issue open -i 3

Example

So far, even at this basic state, it is fairly functional.

cd fiss
fiss list --markdown

| id                   | title                                              | state | assigned |
|----------------------|----------------------------------------------------|-------|----------|
| mfgames/fiss/fiss/6  | Cache foregejo API handle                          | open  |          |
| mfgames/fiss/fiss/7  | Refresh servers, groups, and projects periodically | open  |          |
| mfgames/fiss/fiss/8  | Show progress while syncing with server            | open  |          |
| mfgames/fiss/fiss/9  | Teach cache sync to only sync certain projects     | open  |          |
| mfgames/fiss/fiss/10 | Show information after creating a new issue        | open  |          |
| mfgames/fiss/fiss/11 | Allow for body/-b to edit the body text            | open  |          |
| mfgames/fiss/fiss/12 | Update to new version of foregejo API              | open  |          |
| mfgames/fiss/fiss/13 | Implement subscriptions                            | open  |          |
| mfgames/fiss/fiss/14 | Do not show closed issues by default               | open  |          |
| mfgames/fiss/fiss/15 | Do not show archived projects by default           | open  |          |
| mfgames/fiss/fiss/16 | Get flake working as input for another flake       | open  |          |

You can also see this list on our forge[5].

5: https://src.mfgames.com/fiss/fiss/issues

Future

So, we think this tool has potential. We'll be using it and improving it slowly as we find pain points or things where it doesn't work. At minimum, the goals are:

Add, create, and list tags on issues
Implement milestones
Implement sub-projects
Be able to edit other elements of the item (`fiss edit -i 3`)
Be able to open up the page from the CLI (`fiss web -i 3`)
Get it working properly with NixOS flakes
Be more elegant in retrieving issues
Implement the subscription control so we can decide to include 100s of projects automatically

Metadata

Project:

- Project ID: 0194c2b5-a914-780a-8e3c-d58c3fc45770</li>

Categories:

Fiss

Footer

Below are various useful links within this site and to related sites (not all have been converted over to Gemini).