Work offline and sync your changes back to Jira later. Create issues, modify issues, view stats, run Jira health queries.. All from a friendly git-like CLI.
A few options exist:
- Install via brew on macOS
- Pull and run the latest docker image
- Clone the source code and use docker compose
- Install with pip
brew tap mafrosis/jira-offline
brew install jira-offline
Unfortunately you need an access token for even public packages hosted on Github. Get yours from your settings. Pull the docker image and run it:
echo "$GITHUB_TOKEN" | docker login -u mafrosis --password-stdin docker.pkg.github.com
docker pull docker.pkg.github.com/mafrosis/jira-offline/jira-offline:dev
docker run --rm -it docker.pkg.github.com/mafrosis/jira-offline/jira-offline:dev
git clone https://github.com/mafrosis/jira-offline.git
cd jira-offline
docker-compose build jira-offline
docker-compose run --rm jira-offline
If you know what you're doing, then simply use a virtualenv. For example:
python3 -m venv jira && source jira/bin/activate
pip install jira-offline
See the Github Issues for a comprehensive list.
- You can't change the state of an issue (eg. In Progress -> Done) (GH21).
- You can't change an issue's type from (for example) Bug -> Story (GH20).
- There are mandatory fields required on Jira project screens (GH16).
- It's slow. Reading and writing all data to a single JSONL file is inefficient, and the use of the Pandas library is making the CLI slow (GH13).
- No support for the same project key from two different Jiras (an edge-case at this stage).
- There's a known race condition where a Jira project's issuetypes and priority values can be changed whilst working offline. This could mean that broken issues are created offline (GH22).
jira-offline
ought to work for both Jira Cloud and Jira Server. If you have trouble, please open
an issue!
In Jira Cloud, you have the option to create an API token. This is recommended, rather than using your plain password. You use the token in the same way as the password when using basic auth.
NB: The following examples assume jira
is available in $PATH
The clone
command is used to to setup a new project, which takes a single URI describing your
project.
There are two auth options, basic and oAuth.
Basic auth is quick and takes your existing username and password. Beware that this will write your password into the config file on disk.
jira clone --username benji https://jira.atlassian.com/PROJ
You will be prompted for your password, or API token if you're using Jira Cloud.
oAuth is preferred, as it's token based and doesn't require your password. However it requires the
setup of an Application Link
on the Jira server.
jira clone --oauth-private-key=applink.pem https://jira.atlassian.com/PROJ
NB: The following examples assume jira
is available in $PATH
Use clone
to add a project:
jira clone https://jira.atlassian.com/PROJ
In order to contribute, please fork this repo on Github and raise pull a request with your changes.
You can see a simple development/debugging workflow in the debugging section.
There are four types of testing/validation in the source code:
- Linting of syntactic code errors, and other Python style issues with
pylint
- Typechecking of the python, based on the type-hints in the source using
mypy
- Unit testing via
pytest
, by running all the tests - Integration testing - which requires a local instance of Jira
The Makefile
run the first three steps in order, when you invoke the make
command on its own.
These three checks are also run on every pull request - and must pass for your code to mergeable.
You can invoke any individual stage directly with:
make lint
make typecheck
make test
make integration
The simplest way to debug before opening an issue or contributing is to run the application from
source code in a docker container, using the test
image.
-
Clone the source code to your machine
-
Build the main & test docker images:
docker-compose build jira-offline
docker-compose build test
- Edit
docker-compose.yml
on line 5, to use the-test
image:
jira-offline:
image: mafrosis/jira-offline-test
-
Add a breakpoint in the code with
import ipdb; ipdb.set_trace()
-
Run the main docker image, which will then break:
docker-compose run --rm jira-offline <CMD>
None of the existing clients use the "offline" approach taken by this tool:
danshumaker/jira-cli
- A full featured node.js CLI. This might be a better option ifjira-offline
lacks features you need.keepcosmos/terjira
- Feature-rich Ruby CLI with a neat interactive query function.mikepea/go-jira-ui
- A neat ncurses client focussed on listing issues and making simple changes.foxythemes/jira-cli
- A handsome node.js REPL-style interactive CLI. A very different approach fromjira-offline
.toabctl/jiracli
- A simple CLI for Jira. Not actively maintained.alisaifee/jira-cli
- Another unmaintained and poorly-documented CLI.