If you are using tools like GIT and Maven, chances are you are using the command line a lot. I know I am. So, for me, it was always annoying to open the browser, log on Redmine and search for my open issues, just to find out the ID of that particular issue that I’m going to associate my GIT commit with. (By the way, if you still don’t know this, if you add “IssueID #XXXXX” in your GIT commit message, Redmine will be able to associate your changes with the issue. Very handy when tracking changes.)

I always liked to use the command line based tool Todo.txt to manage my to-do list. No need to leave the terminal to check what I have to do. So, I thought it would be cool if we had a similar tool for Redmine. A simple command line interface to check your open issues, change their status, add comments and so on. Just like you would do with your to-do list. And that’s why we created RedToDo.

RedToDo is a command line interface for Redmine that allows you to view and manage issues. It’s not intended to be a comprehensive command line interface to Redmine, but instead focus on the most common day to day tasks you have to do.

RedToDo is a Java based tool and as such can run on multiple platforms. It is also an open source tool, released under the Apache 2.0 license. So, use it as you wish!

Available commands:

RedToDo can be executed by running the distribution jar file available here. Log as user guest/password guest.

Example:

java -jar redtodo-1.0.0-SNAPSHOT-jar-with-dependencies.jar <OPTIONS>

There is also a “redtodo.sh” script that you can use to run it. Here are the available commands:

> ./redtodo.sh -h

redtodo.sh ACTION OPTIONS

Actions:
 list|ls - Usage: redtodo.sh list [-s STATUS_LIST] [-p PROJECT_KEY] [-u USER_NAME] [-g] PAGE_NUMBER

 show|s - Usage: redtodo.sh show [-f] ISSUE_ID

 change|ch - Usage: redtodo.sh change ISSUE_ID STATUS_ID [COMMENT]

 comment|co - Usage: redtodo.sh comment ISSUE_ID COMMENT

Try redtodo.sh help ACTION for more information about an action
> ./redtodo.sh help list

Lists issues. By default, lists only open issues assigned to you.
Usage: redtodo.sh list [-s STATUS_LIST] [-p PROJECT_KEY] [-u USER_NAME] [-g] PAGE_NUMBER

 -s|--status STATUS : Lists issues in the informed status.
 Possible values are open, closed and sll
 -p|--project PROJECT_KEY: Lists only issues for the project with PROJECT_KEY.
 Use --all for all
 -u|--user USER_NAME : Lists all issues assigned to a particular user.
 Use --all to all users
 -g|--page PAGE_NUMBER : Page number to list.
 Issues are listed in pages of 20 elements each.
> ./redtodo.sh help show
Shows information about an issue.
Usage: redtodo.sh show [-f] ISSUE_ID
 -f|--full it will show all the details about an issue
 ISSUE_ID is the issue identifier
> ./redtodo.sh help change

Change the status of an issue.

Usage: redtodo.sh change ISSUE_ID STATUS_ID [COMMENT]

 ISSUE_ID is the issue identifier
 STATUS_ID is the numeric ID of the new status
 COMMENT is a comment that you can add to your change.
> ./redtodo.sh help comment
Add a comment to an issue.
Usage: redtodo.sh comment ISSUE_ID COMMENT
 ISSUE_ID is the issue identifier
 COMMENT your comment.

Build from source:

If you are building from source:

1. First, you need to install Maven

2. Then clone out git repository:

git clone https://guest@helpdesk.toolscloud.net/git/redtodo.git

Password is guest

3. Run:

cd redtodo
mvn clean compile assembly:single

4. The executable jar will be in the target folder

INSTALATION

Download the distribution file available here and unzip it. Log as user guest/password guest to download the file.

RedToDo is self explanatory. When you run it for the first time, it will give you all the configurations you need to do. See:

> ./redtodo.sh
It seems you didn't create your configuration file yet.
In order to use RedTodo, you need to create this file: /Users/yourname/.redtodo/config.properties with the following content:
redmineHost=<URL to your Redmine Host>
apiAccessKey=<Your API access key>
The redmineHost is simply the URL that you use to access Redmine.
Here is how to get your API access key:
1. Login into Redmine
2. Click on My Account
3. You'll see on the right site "API Access Key". Click on the Show link below it.
4. Copy the sequence of characters that will show and put on your configuration file.
IMPORTANT: Make sure to enable REST web service in your Redmine instance.
This can be done by the Redmine administrator in the Settings/Authentication tab.

Known issues and limitations

1. RedToDo is a beta software. It was tested on MacOSX, but it should work on other platforms. You just have to try it.

2. To change the issue status, you have to inform the new status id. Unfortunately, the Redmine REST API does not provide a feature to retrieve all the available status at this time. It is also not easy to find the id of a status, but you have a few options: ask your Redmine administrator to find out the id of a particular status. He/she can do that going in to the status update screen and looking at the id in the URL when they edit a status. Another option is to find an issue with the status you want to have the id and use the ./redtodo.sh show ISSUE command. It will print the id of that status.