~mrshll1001/ticketsnake

#Ticketsnake

A bare-bones Redmine CLI tool written in Python with minimal dependencies

You may also enjoy ticketbasher, which is a companion Bash wrapper to ticketsnake.

#Why?

I prefer using CLI tools where possible rather than firing up a big ol' web browser to view a ticket
There's plenty Redmine CLI tools but they all need to be installed via pip or like npm or something and I wanted something with minimal dependencies.
I like writing pretty-formatted output in my terminal
Fun

#Coverage

Ticketsnake does not aim to cover all of the Redmine API; just those bits that I use.

This is mostly:

Issues: list, view, add/remove watchers, and update
Projects: list, view
Statuses: list

#Extra features

#Save user ids locally

When manipulating issues you may want to reassign them and this requires the user id. This isn't very friendly for humans who don't think of people as numbers.

Unfortunately, the GET /users.json API endpoint is protected and limited only to administrators of instances. There is no guarantee that you are an administrator, so ticketsnake can be configured to "harvest" any user ids it encounters from tickets alongside their human-friendly names, so that you have access to them locally.

In your config file you can set save_users_locally to true, which turns this feature on. Whenever you run a command on ticketsnake that returns issue information (issue view or issue list, usually), ticketsnake will inspect the issue for user information and extract/save it. It does this for authors, assignees, and authors of notes/updates to the ticket if issue journals are also included.

It will save the information to $XDG_DATA_HOME/ticketsnake/users.json

I decided to do this this way to keep the logic for each action as simple as possible, and to make ticketsnake more composable. Rather than implementing a system of managing and resolving local aliases for user ids — which results in more code and more mental burden for the CLI user remembering aliases for everyone — you can write a quick and dirty script to handle grabbing a user id via another program.

Here's an example in bash which implements a basic ticket reassignment workflow using jq, fzf, cut and ticketsnake

#!/usr/bin/env sh

CHOSEN_ID=$(jq -r '.users[] | "\(.id) \(.name)"' $HOME/.local/share/ticketsnake/users.json | fzf | cut -f 1 -d ' ')


# We'll assume that $1 is a valid ticket number!

ticketsnake issue update $1 --assignee "$CHOSEN_ID"

The best way to get a large number of user ids is to run issue list --limit 200 to return a large number of tickets.

#Installation

#via Make

Install via make, which copies the script to ~/.local/bin/ticketsnake as an executable.

make install installs
make uninstall uninstalls it

#via Pip

Install as a python package via pip and add the ticketsnake executable to your Python environment's PATH.

pip install git+https://git.sr.ht/~mrshll1001/ticketsnake.git@main to install directly from the repository's main branch
pip install . to install a locally checked-out copy
pip uninstall ticketsnake to uninstall

#Dependencies

Python 3
Python Libraries
- click
- json
- os
- sys
- requests

As far as I'm aware, this means that the only dependency not in the standard library is click, which is available in many distro package repos.

If you're on Debian run

sudo apt install python3-click

#Configuration

Configuration is via a JSON config file, located at $XDG_CONFIG_HOME/ticketsnake/config.json.

You can create it by hand or you can run the init command to generate it for you via some prompts.

It takes the following keys:

remine_base_url: URI formatted string, used to make requests to the Redmine instance
redmine_api_key: String, get this from your redmine instance to authenticate ticketsnake. There are no plans to support auth via oAuth2
save_users_locally: Boolean. Set to true if you want to keep local copies of users so that you can compose workflows which don't result in you needing to remember ids or configure aliases

Example:

{
	"redmine_base_url": "https://example.org",
	"redmine_api_key": "your-api-key-here",
	"save_users_locally": true
}

#Issue Tracking

Ticketsnake's issue tracker can be found at the following URL:

https://todo.sr.ht/~mrshll1001/ticketsnake

#Contributing

I am open to contributions which suggest better or more elegant ways of doing the things that Ticketsnake does including improvements to the Makefile. Other than that; I won't be maintaining the pyproject.toml file to enable installation via pip, so if that needs updating then this is a very welcome contribution to help ensure that pip users can still install the tool.

Other than that, I am not particularly seeking contributions. Ticketsnake is primarily a personal tool used to make my life at work a bit cosier and smoother while having fun writing some code. I released it as a public FLOSS project as a matter of principle.

refs

clone