jirasify
Terminal UI for logging work and moving Jira issues, built with Textual.
The distribution name on PyPI is jirasify; the main CLI command is jirasify-tui; the importable Python module is jiratui.
Install
pip install jirasify
Each command (jirasify, jirasify-tui, jirasify-list) has a --version
flag that prints the installed version and a bundled changelog.
Configure
On first run, jirasify-tui writes a template config to ~/.local/etc/jiratui/config.yaml and prints a usage page. Edit the file (or answer the interactive prompt to fill it) with your Jira URL, project key, and username.
Your Jira token is read from the environment variable named by authentication.token_env (default: JIRATOKEN):
export JIRATOKEN=your_token
- Self-hosted Jira (Data Center / Server): use a Personal Access Token. It is sent as
Authorization: Bearer <token>. - Atlassian Cloud (URL contains
atlassian.net): use an API token from your Atlassian account. It is combined withassignee.username(your account email) via HTTP Basic auth.
Both hierarchy conventions are supported: Data Center's Epic Link custom
field, and Cloud's standard parent field for the Epic → Story link. The
subtask issue type name is auto-discovered per project (Cloud team-managed
projects use Subtask; most others use Sub-task).
The Sprint / Epic Link / Epic Name / Parent Link custom fields are matched
first by display name and then by their Greenhopper schema.custom value,
so localized or renamed installations still resolve. The enhanced JQL
endpoint (POST /rest/api/2/search/jql) is tried first and the client
falls back to the classic /rest/api/2/search on any of 400/404/405/501,
so old Data Center instances that answer differently still work.
Verify connectivity before launching the TUI:
jirasify-tui --test
Prints the configured URL and token env var, then hits /rest/api/2/myself. Exits with a non-zero status on missing config, unset token, or auth failure.
Usage
jirasify-tui
| Key | Action |
|---|---|
l |
Log view |
o |
Overview |
r |
Monthly report |
t/w |
Today's / this week's report |
m |
This month's report |
s |
Change status of selected issue |
e |
Set estimate on selected issue |
p |
Start / stop timer on selected issue (locks; second press prompts to log elapsed) |
h |
Help |
Ctrl+R |
Refresh |
q |
Quit |
Time input accepts 30m, 1h, 2h30m, 1d (a day = 8h).
jirasify
pip install jirasify also installs a jirasify command that turns a
structured Markdown file into Jira user stories using the same
~/.local/etc/jiratui/config.yaml and JIRATOKEN env var as jirasify-tui.
Expected Markdown layout:
# My Epic Name - User Stories
## 1. Project Overview
Free text.
---
# Phase 1 - Foundations
## User Story 001 - Inventory Environment
**Estimate:** 15 h
> As a developer, I will document ... so that ...
### Scope
- Item A
- Item B
### Substories
- Break out first sub-piece
- Break out second sub-piece
### Acceptance Criteria
- Criterion 1
- Criterion 2
- The top-level
# ...heading (any H1 that is not a# Phase ...) is used as the Epic name. A trailing- User Storiessuffix is stripped. - Stories are only picked up under a
## User Story ...heading inside a# Phase ...section. - Recognised subsections:
Scope,Validate,Include,Examples,Substories,Acceptance Criteria. - Each
### Substoriesbullet becomes a Sub-task in Jira under the parent story. Substories are excluded from the story's Jira description so they aren't duplicated. - A
**Tags:** foo, bar, bazline anywhere in a user story block adds extra Jira labels (spaces replaced with_). Combined with the auto-generatedPhase_...label on every created issue.
Commands
jirasify --example # write ./example.md (plain markdown starter)
jirasify --template --file stories.md.j2 # write an Ansible/Jinja2 template
jirasify --file stories.md # parse + write .jirastories.state.json
jirasify --file stories.md --create # ensure Epic exists, create missing stories linked to it (idempotent)
jirasify --file stories.md --status # key/status/assignee/epic/estimate/used per story, grouped by phase with totals
jirasify --file stories.md --epic VOS-100 # relink stories to a specific epic
jirasify --file stories.md --epic VOS-100 --story VOS-142 # relink a single story
jirasify --file stories.md --link-epic # relink recorded stories to the Epic named by the H1 (creates it if missing)
jirasify --file stories.md --tag # add Phase_ and **Tags:** labels to already-created stories/substories (union)
jirasify --file stories.md --delete # delete every recorded issue (prompts unless --yes)
jirasify --reverse VOS-1234 # print a markdown reconstruction of an Epic and its stories
jirasify --reverse VOS-1234 --save # write it to <Epic_Name>.md (spaces -> _)
--create skips stories that already have an issue_key recorded in
.jirastories.state.json, and also skips summaries that already exist in the
target project, so re-runs won't duplicate issues. If no Epic with the H1's
name exists, one is created before the stories. Substories are handled the
same way — each story tracks its sub_keys map, and existing subtasks are
adopted by summary before creating new ones.
--reverse also emits each fetched story's subtasks as a ### Substories
block, so round-tripping --create then --reverse preserves the
sub-structure.
Each created story (and its substories) is tagged with a Jira label derived
from its markdown phase — spaces are replaced with underscores, e.g.
Phase_1_-_Foundations. This lets jirasify-list --epics --full render a
phase level in its tree; the labels are inert otherwise.
Any **Tags:** ... line in a user story adds additional labels to that
story (and its substories). --tag performs a label alignment on already-
created issues — it unions the phase label and markdown tags onto each
recorded issue via an atomic PUT update op, so any Jira-side labels you
added manually are preserved.
--reverse reads back the labels and emits one # Phase N - ... heading
per phase, and a **Tags:** ... line under stories that have non-phase
labels — so create → reverse round-trips the tag structure.
--delete undoes --create for the current state file: it lists the
recorded stories and substories, prompts for confirmation (skip with
--yes), then deletes each in Jira (substories first). The epic itself
is left alone — remove it in the Jira UI if you want.
Ansible / Jinja2 template
--template emits a .j2 scaffold expecting these variables:
epic_name(string)project_overview(string, optional)phases: list of{ name, stories: [ { id, summary, estimate, description, scope?, acceptance_criteria? } ] }
Render it with ansible.builtin.template (or jinja2.Template) to produce
a stories.md, then run jirasify --file stories.md --create.
jirasify-list
pip install jirasify also installs a jirasify-list command for read-only
listing of Jira objects, using the same config as jirasify-tui.
jirasify-list --epics # Epics in jira.project (config), excluding Cancelled and Done
jirasify-list --epics --key VOS # override the project key
Status filters (mutually exclusive)
jirasify-list --epics --active # status = Implementing
jirasify-list --epics --planning # status = Planning
jirasify-list --epics --done # status = Done
jirasify-list --epics --cancelled # status = Cancelled
Without any of these flags, Cancelled and Done epics are hidden by default.
Parent Link filter
jirasify-list --epics --parent VOS-100 # exact parent (JQL: "Parent Link" = VOS-100)
jirasify-list --epics --parent VOS # any parent whose key starts with VOS-
Full hierarchy
jirasify-list --epics --full # also show stories under each epic and subtasks under each story
--full issues one extra batched JQL for all epic children ("Epic Link" in (…))
and one for all subtasks (parent in (…)), regardless of item count.
Output
Epics are grouped by their Parent Link and printed as a tree with box-drawing
branches (├──, └──, │):
VOS-100 Digital Platform Modernization
├── VOS-215 Implementing Jane Doe Artifactory PyPI
│ ├── Phase 1 - Prepare Artifactory
│ │ ├── VOS-231 In Progress Bob Provision PyPI local repo
│ │ │ └── VOS-232 To Do Alice Configure retention
│ │ └── VOS-233 To Do Bob Assemble virtual PyPI
│ └── Phase 2 - POC Publishing Pipeline
│ └── VOS-241 To Do Alice Build POC publishing pipeline
└── VOS-220 To Do Bob Sisyphos Onboarding
└── (no phase)
└── VOS-260 To Do Alice Ad-hoc story
VOS-105 Infrastructure 2026
└── VOS-311 Implementing Alice VMware 9.1 Enablement
(no parent)
└── VOS-999 Planning Unassigned Ad-hoc Epic
Columns per row: issue key, status, assignee (truncated to 32 chars with …),
and the label — Epic Name for epics (falls back to summary when the Epic Name
custom field is absent), summary for stories and subtasks. Without --full
only the epic level is shown; with --full, stories are grouped under a phase
row derived from the story's Phase_... Jira label (falls back to (no phase)
when a story has no such label — typical for stories created outside jirasify
or before phase-labelling was added).
Rows are colorized when stdout is a terminal: cyan parent header and phase, magenta epic, green story, blue subtask. Piping or redirecting produces plain output.
1 maintainer
Metadata
1 maintainer
Release files for jirasify 2.7.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| jirasify-2.7.5.tar.gz | 37.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| jirasify-2.7.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 79.3 kB
Release files / jirasify-2.7.5.tar.gz
| Download URL | jirasify-2.7.5.tar.gz |
|---|---|
| Size | 37.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ba0c1f1c7adc0f25bafa203b0c5c337bb6c4a70c2aa6f3e3515f3eb398a13d6c
|
|
BLAKE2b-256 checksum How to use checksums |
2bb74b3d1e1a97c7ce2aa4d9b18b78ecab927bf193ce5b737f1b7c8d4e249a8f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / jirasify-2.7.5-py3-none-any.whl
| Download URL | jirasify-2.7.5-py3-none-any.whl |
|---|---|
| Size | 41.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6466d4cdc9e88c02c5b9ae99f32581fd9a666835497133b6279cf3ef0d38a229
|
|
BLAKE2b-256 checksum How to use checksums |
a3fdff022fe4e72673cf980f3b92357c9dd7f3f1009fe34335511a3e2bf88357
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for jirasify 2.7.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
