Fiss

News

• 2025-02-20 Introducing Fiss
• Blog Archives

Introduction

A command-line interface for working with forge issues inspired by TaskWarrior.

⚠ This is alpha work. It barely works, it requires manual editing of configuration files, it doesn't play well with servers and throttling, and basically it is a large, crude hammer at this point. There is a lot of work to be done on it, but it does do the minimum it needs to.

Fiss is a command-line tool (fiss) that treats issues from forges (Forgejo only) as tasks. This uses the state (open, closed) and the assigned do to figure out if a task is available (open), started (open and assigned), or done (closed). In the future, this will take into account dependencies to allow blocking of tasks, tags for grouping those, and milestones for projects.

Configuration

Configuration file uses the XDG standard but will normally put files into $HOME/.config/fiss/fiss.yaml.

servers:
  mfgames:
    url: https://src.mfgames.com/
    forge: forgejo
    token: NotGonnaTellYou
    groups:
      fiss:
        projects:
          fiss: {}

Usage

Right now, there is no automatic retrieval of tasks, so the cache sync command needs to be run after the configuration is setup. As with most commands, the logging is mostly silent but using -v will increase verbosity. More -v will add details with -vvvv being the most.

fiss cache sync

Once issues are pulled down, they can be listed by either of the two commands:

fiss list
fiss issue list

Creating issues requires knowing the server (from the configuration), the organization/group name, the project/repo name. These can be stored in environment variables to simplify the code (FISS_SERVER, FISS_GROUP, and FISS_PROJECT respectively).

fiss add -s mfgames -g fiss -p fiss --title "Name of the issue"

export FISS_SERVER=mfgames
export FISS_GROUP=fiss
export FISS_PROJECT=fiss

fiss add -t "Second Issue

The rest of the commands assume the three environment variables are set.

Issues can be open and closed using their number.

fiss open --issue 3
fiss close -i 3

As with most CLIs, --help on any command will give more details.

Environment Variables

In addition to the environment variables above, the following are also used:

• FISS_CONFIG_DIR: The directory that contains the configuration file. This defaults to the $XDG_CONFIG_HOME/fiss if not defined.
• FISS_CACHE_DIR: The directory that contains the cached data from the servers. This defaults to the $XDG_CACHE_HOME/fiss if not defined.