JCT — JIRA Commit Tool CLI

A command-line tool that connects your Jira board to your Git workflow. Select an issue, choose a commit type, write a title — JCT creates the branch (if needed) and formats the commit so Jira detects it automatically.

Works with Scrum and Kanban projects and follows Git Flow conventions. Supports multiple Jira accounts with per-repository configuration.

Prerequisites

• Node.js ≥ 18
• Git installed and a repository initialized
• A Jira account with API access
• A Jira API token — generate one at id.atlassian.com/manage-profile/security/api-tokens

Installation

npm install -g jct-cli

First-time setup

Run the interactive wizard to connect JCT to your Jira account:

jct config jira

You will be prompted for:

| Field | Description | Example | |---------|---------------------------------------------|----------------------------------------| | User | Your Atlassian account email | [email protected] | | Token | Your Jira API token | ATATT3xFfG... | | URL | Your Jira workspace URL (no trailing slash) | https://mycompany.atlassian.net | | Project | Default Jira project key | MYPROJ |

All credentials are encrypted with AES-256-GCM and stored at ~/.jct/config.enc. The master key lives at ~/.jct/master.key and never leaves your machine.

After connecting your account, set the active sprint (Scrum) or load board issues (Kanban):

jct config jira --sprint    # Scrum: set active sprint
jct config jira --issues    # both: refresh issues cache
# or short:
jct c j -s
jct c j -i

Daily usage

jct

JCT will:

1. Validate your Jira credentials
2. Auto-detect if this repo has a .jct config — if not, run the repo setup wizard
3. Scrum: check whether the current sprint is still active and show its issues Kanban: load open board issues (status ≠ Done)
4. Ask for a commit type (feat, fix, docs, refactor, test, chore, style, perf)
5. Ask for a short commit title
6. Optionally ask for a description
7. Checkout (or create) the issue branch — e.g. feature/PROJ-123
8. Stage all changes and commit with the format:

PROJ-123: feat / add login validation

Git state detection

Before committing, JCT checks for in-progress Git operations and stops with a clear message if it finds:

• git merge in progress
• git rebase in progress
• git cherry-pick in progress

Resolve the operation first, then run jct again.

Multi-account support

JCT supports multiple Jira accounts. Each repository stores its own .jct file (added to .gitignore automatically) pointing to which account and project to use.

~/.jct/config.enc   ← encrypted global store: all accounts + credentials
<repo>/.jct         ← per-repo: which account + project + sprint (no credentials)

First run in a new repo

When you run jct in a repo that has no .jct file, the setup wizard runs automatically:

1. Choose an existing account or add a new one
2. Select the Jira project for this repo
3. Configure the active sprint (Scrum) or load board issues (Kanban)
4. .jct is written and added to .gitignore

Working across machines

If you clone a repo that already has a .jct file but your machine doesn't have that account configured, JCT detects this and asks you to provide the credentials for that account alias.

Commands reference

jct

Runs the main commit flow. Triggers repo setup wizard if .jct is missing.

jct status · jct s

Shows the current JCT state for this repository: active account, project, sprint or Kanban board, and number of cached issues.

jct status
jct s

jct config · jct c

Shows current configuration and lists available subcommands.

jct config jira · jct c j

Interactive wizard — configure all Jira fields at once.

jct config jira
jct c j

Individual flags — each launches a single prompt:

| Long form | Short | Action | |----------------------------|-----------|-----------------------------------| | jct config jira --user | jct c j -u | Update email | | jct config jira --token | jct c j -t | Update API token | | jct config jira --url | jct c j -r | Update Jira workspace URL | | jct config jira --project| jct c j -p | Update default project | | jct config jira --sprint | jct c j -s | Fetch and set active sprint | | jct config jira --issues | jct c j -i | Refresh sprint issues from Jira|

jct config jira account · jct c j a

Manage the Jira accounts stored on this machine. Lives under jira because these are Jira accounts.

jct config jira account     # list all accounts (marks the active one for this repo)
jct c j a

| Long form | Short | Action | |----------------------------------------|--------------|--------------------------------------------------| | jct config jira account --add | jct c j a -a | Add a new Jira account (alias, email, token, URL) | | jct config jira account --switch | jct c j a -s | Change the active account for this repo | | jct config jira account --remove | jct c j a -r | Remove an account (with confirmation) |

jct me

Displays your current configuration (token is hidden).

jct me

jct lan

Switch the CLI language between English and Español.

jct lan

jct version

Prints the JCT version number.

How it works internally

~/.jct/
├── master.key    # 32-byte random key (AES-256-GCM), generated once on first run
├── config.enc    # all Jira accounts encrypted (email, token, URL per account)
└── db.enc        # encrypted database — projects, sprints, and issues cache

<repo>/
└── .jct          # per-repo config (account alias + project + sprint) — in .gitignore

• Credentials are decrypted once per session and cached in memory — no repeated disk reads.
• The per-repo .jct stores no credentials — only which account alias and project to use.
• Sprint issues are fetched from the Jira Agile API and stored locally so you can commit offline.
• The master key never leaves your machine. If you delete it, your config is unrecoverable — run jct config jira to reconfigure.

Troubleshooting

401 Unauthorized

Your API token or email is wrong. Re-run:

jct c j -t
jct c j -u

403 Forbidden

Your token doesn't have permission to access the project. Check token scopes at id.atlassian.com.

404 Not Found

The project key or Jira URL is incorrect:

jct c j -r
jct c j -p

Network error

Check your internet connection and that the Jira URL is reachable.

Sprint appears expired / no issues shown

The sprint end date has passed. Fetch the new sprint (Scrum) or refresh board issues (Kanban):

jct c j -s    # Scrum: set new sprint
jct c j -i    # both: refresh issue cache

"Not a git repository"

Run jct from inside a git repository (git init if needed).

"Merge / rebase / cherry-pick in progress"

Finish or abort the in-progress git operation first:

git merge --abort
git rebase --abort
git cherry-pick --abort

Repo asks for account setup every time

The .jct file may be missing or corrupt. Run:

jct c j a -s    # switch/assign an account to this repo

Account works on one machine but not another

The config.enc is local to each machine. Add the account on the new machine:

jct c j a -a    # add account with the same alias as in .jct

Config seems corrupted

Delete the encrypted files and reconfigure:

rm ~/.jct/config.enc ~/.jct/db.enc
jct config jira

License

MIT