Package: jira-offline
Git-like CLI for using Jira offlineWork 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.InstallationA few options exist:Install via brew on macOSPull and run the latest docker imageClone the source code and use docker composeInstall with pipUse Homebrew (macOS)brew tap mafrosis/jira-offline
brew install jira-offlineDocker imageUnfortunately you need an access token for even public packages hosted on Github. Get yours fromyour 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:devClone and use docker composegit clone https://github.com/mafrosis/jira-offline.git
cd jira-offline
docker-compose build jira-offline
docker-compose run --rm jira-offlineInstall into a virtualenv with pipIf you know what you're doing, then simply use a virtualenv. For example:python3 -m venv jira && source jira/bin/activate
pip install jira-offlineKnown LimitationsSee theGithub Issuesfor 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 Cloud vs Jira Serverjira-offlineought to work for both Jira Cloud and Jira Server. If you have trouble, please open
anissue!DifferencesIn Jira Cloud, you have the option tocreate an API token.
This is recommended, rather than using your plain password. You use the token in the same way as the
password when usingbasic auth.Quick StartNB: The following examples assumejirais available in$PATHCloneTheclonecommand is used to to setup a new project, which takes a single URI describing your
project.Authentication to JiraThere are two auth options, basic and oAuth.Basic AuthBasic auth is quick and takes your existing username and password. Beware that this willwrite your
password into the config file on disk.jira clone --username benji https://jira.atlassian.com/PROJYou will be prompted for your password, or API token if you're using Jira Cloud.oAuthoAuth is preferred, as it's token based and doesn't require your password. However it requires the
setup of anApplication Linkon the Jira server.jira clone --oauth-private-key=applink.pem https://jira.atlassian.com/PROJHow To UseNB: The following examples assumejirais available in$PATHHow to configure a new Jira projectUsecloneto add a project:jira clone https://jira.atlassian.com/PROJContributingIn 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 thedebugging section.Run The TestsThere are four types of testing/validation in the source code:Linting of syntactic code errors, and other Python style issues withpylintTypechecking of the python, based on the type-hints in the source usingmypyUnit testing viapytest, by running all thetestsIntegration testing - which requires a local instance of JiraTheMakefilerun the first three steps in order, when you invoke themakecommand 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 lintmake typecheckmake testmake integrationDebuggingThe simplest way to debug before opening an issue or contributing is to run the application from
source code in a docker container, using thetestimage.Clone the source code to your machineBuild the main & test docker images:docker-compose build jira-offline
docker-compose build testEditdocker-compose.ymlon line 5, to use the-testimage:jira-offline:
  image: mafrosis/jira-offline-testAdd a breakpoint in the code withimport ipdb; ipdb.set_trace()Run the main docker image, which will then break:docker-compose run --rm jira-offline <CMD>Comparison to other Jira CLIsNone 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-offlinelacks 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.