imdone-cli 💡

Your Jira or GitHub issues as markdown files in your repo. Edit issues, add comments, attach planning docs (tasks, designs, specs) — all locally in markdown. Changes sync bidirectionally with imdone push and imdone pull. Planning context lives with your code where your team and AI can access it.

Prerequisites

• Node.js v22 or higher installed
• git installed
• For Jira:
  • Jira account with API access
  • A Jira API token with read and write permissions for the project
• For GitHub:
  • GitHub account with repository access
  • A GitHub Personal Access Token with repo scope
• A git repository used for your software development

Get started:

# 1) Install
npm i -g imdone-cli

# 2) Initialize and pull issues
imdone init

# 3) Open stories in your editor (Markdown next to your code)
code . # nvim .

What you'll see: A backlog/current-sprint/ directory with organized folders—one per issue. Each issue folder contains the main issue content (e.g., issue-PROJ-123.md for Jira or 1-Issue_title/ for GitHub), comments (comments-PROJ-123.md or comments-1.md), and an attachments/ folder. Edit markdown locally; imdone push syncs changes back to your provider.

backlog/
├── .imdone/
│   ├── config.yml
│   └── templates/
│       └── story.md
├── current-sprint/
│   ├── PROJ-123-Fix_login_bug/
│   │   ├── attachments/
│   │   │   └── error-screenshot.png
│   │   ├── comments-PROJ-123.md
│   │   └── issue-PROJ-123.md
│   └── PROJ-124-Add_user_dashboard/
│       ├── attachments/
│       ├── comments-PROJ-124.md
│       └── issue-PROJ-124.md

Two commands you'll use a lot

imdone pull   # Bring issues/comments/attachments into Markdown
imdone push   # Push your Markdown edits back to your provider

Uninstall anytime: imdone destroy && npm uninstall -g imdone-cli (your code is untouched; backlog/ is git-ignored).

🙋 Support & Feedback

Found a bug or have a feature request? We'd love to hear from you!

• Website: imdone.io
• Email: [email protected]
• Discord: Join our Imdone users group for real-time support and discussions

🔧 Commands

📋 Output Formats: Many commands support the -f, --format option to change output format. Available formats are: json, yaml, csv, text (default).

init – Initialize Issue Tracking Integration

imdone init

Initialize integration with Jira or GitHub Issues. You'll be prompted to select your provider and provide the necessary configuration.

Common Options:

• --name - Project name
• --provider - Issue tracking provider: jira or github

Jira Options:

• --jira-url - Jira instance URL
• --jira-project-key - Jira project key
• --jira-username - Jira username
• --jira-api-token - Jira API token
• --jql - JQL query for filtering issues

GitHub Options:

• --github-owner - GitHub repository owner (auto-detected from git remote)
• --github-repo - GitHub repository name (auto-detected from git remote)
• --github-token - GitHub Personal Access Token

GitHub Integration Notes:

• imdone pull is fully functional for GitHub
• imdone push supports issue content, labels, and comments for GitHub issues
• imdone add fully supports creating GitHub issues
• GitHub owner and repo are auto-detected from your git remote origin URL

clone – Clone Remote Backlog Repository

imdone clone

Options:

• --remote-url
• --backlog-dir

Clones a remote backlog for easy onboarding.

update – Update imdone-cli Config

imdone update

Alias: u

Pull imdone-cli config from origin/main (using "theirs" strategy).

Options:

• --force - Force the update without prompting when imdone-cli is outdated

pull – Pull Issues from Provider

imdone pull

Options:

• -f, --format <format> - Output format: json, yaml, csv, text (default: text)

Fetches issues, comments, and attachments from your configured provider (Jira or GitHub). Stashes local changes if needed, updates markdown files, and restores your changes.

What gets pulled:

• Issue content and metadata
• All comments (see Working with Comments)
• All attachments (Jira only - see Attachments Without the Browser)
• Status and field updates

Provider-Specific Notes:

GitHub:

• Fetches issues based on state (open/closed), labels, milestones, and assignees
• Maps GitHub states to imdone lists via status configuration
• Handles pagination automatically for large repositories
• Comments are fully supported (pull and push)

Jira:

• Uses JQL queries for flexible filtering
• Full support for comments and attachments
• Sprint and epic integration

push – Push Changes to Provider

imdone push

Lints, pulls, extracts updates, and syncs with your issue tracking provider (Jira or GitHub).

What gets pushed:

• Issue content and metadata changes
• New comments (see Working with Comments)
• New attachments (Jira only - see Attachments Without the Browser)
• Labels

Provider-Specific Notes:

Jira:

• Validates markdown formatting for Jira compatibility
• Converts markdown to Jira markup automatically

GitHub:

• Uses markdown natively (no conversion needed)
• Comments are fully supported

💡 Pro Tip: Use commentRequired:true in task metadata to enforce comments on critical issues before pushing.

add – Create New Issue

imdone add

Alias: a

Creates a new issue (Jira or GitHub) through an interactive guided process, or using provided options. The prompts adapt intelligently based on your provider's capabilities.

Options:

• --project-key [projectKey] - Project key (e.g., PROJ for Jira, owner/repo for GitHub)
• --template [template] - Template to use for the issue (e.g., story, bug)
• --issue-type [issueType] - Issue type (Jira only: Story, Task, Bug, etc.)
• --location [location] - Issue location (Jira only): "backlog" or "sprint"
• --sprint-id [sprintId] - Sprint ID when location is "sprint" (Jira only)
• --summary [summary] - Issue summary/title
• -f, --format <format> - Output format: json, yaml, csv, text (default: text)

Examples:

# Jira: Create issue with all options specified
imdone add --project-key PROJ --template story --issue-type Story --location sprint --sprint-id 123 --summary "New feature request"

# GitHub: Create issue (note: no issue-type or location needed)
imdone add --project-key owner/repo --template story --summary "Bug fix request"

# Interactive mode for any provider
imdone add

Interactive prompts (when options not provided):

1. Template selection - Choose from available templates in .imdone/templates
2. Project selection - Choose which project to create the issue in (only shown when multiple projects are configured)
3. Issue type - Select issue type (Jira only - skipped for GitHub)
4. Location - Choose current sprint or backlog (Jira only - skipped for GitHub)
5. Summary - Enter the issue title/summary

What gets created:

• New issue in your provider (Jira or GitHub) with specified summary
• Markdown content based on selected template (if any)
• Basic structure (Description, Tasks) if no template is used
• Template tags automatically converted to labels (GitHub) or labels field (Jira)
• A provider-specific replay command showing how to create similar issues without prompts
• Automatic pull of the new issue into your local project

Templates: If your project has templates in .imdone/templates, they will be available for selection. Templates provide pre-structured content for consistent issue creation. Tags in templates (e.g., #bug, #urgent) are automatically converted to labels.

Templates can also include special links that automatically create files in the issue's attachments/ directory. See the Auto-File Creation in Templates section under the template command for details.

💡 Replay Command: After creating an issue, the CLI will display the exact command to create a similar issue without prompts, tailored to your provider:

Jira example:

💡 Next time, use: imdone add --project-key "PROJ" --template "story" --issue-type "Story" --location "backlog" --summary "Your issue title"

GitHub example:

💡 Next time, use: imdone add --project-key "owner/repo" --template "story" --summary "Your issue title"

template – Apply Template to Existing Issue

imdone template [issueKey]

Alias: t

Applies a template to an existing Jira issue through an interactive guided process, or using provided options.

Arguments:

• [issueKey] - Issue key to apply template to (e.g., PROJ-123)

Options:

• --template [template] - Template to apply (e.g., story, bug, dod)

Examples:

# Apply template with all options specified
imdone template PROJ-123 --template dod

# Interactive mode - prompts for missing arguments
imdone template

# Prompt for template only
imdone template PROJ-123

Interactive prompts (when options not provided):

1. Issue selection - Choose from available issues in current sprint
2. Template selection - Choose from available templates in .imdone/templates

What gets applied:

• Template metadata (tags, custom fields) is merged with existing metadata

Templates: Templates are markdown files stored in .imdone/templates that provide pre-structured content for consistent issue formatting. Templates can reference existing issue content using ${markdown} to incorporate the current issue content. A default story template is included.

Auto-File Creation in Templates: Templates can automatically create files in the issue's attachments directory using specially formatted links. This works with both imdone add (when creating new issues) and imdone template (when applying templates to existing issues).

[Link Text](./attachments/filename.ext?template=<template_name>)
[Empty File](./attachments/filename.ext)

• Links with ?template=<template_name> create files populated with content from the specified template
  • Template names can be specified with or without the template_ prefix (e.g., story or template_story)
• Links without a template parameter create empty files
• Files are created in the issue's attachments/ directory when the template is used
• Existing files are never overwritten
• If a template is not found, an empty file is created with a warning

Example Template with Auto-File Creation:

# Story Template

## Documents
- [Story Document](./attachments/story.md?template=story)
- [Notes](./attachments/notes.md)
- [Test Plan](./attachments/test-plan.md?template=test)

## Description
Add your story description here...

When this template is used (either with imdone add or imdone template), the system will automatically:

1. Create the attachments/ directory in the issue folder
2. Create story.md with content from the story template
3. Create an empty notes.md file
4. Create test-plan.md with content from the test template

merge – Resolve Conflicts

imdone merge

After resolving conflicts manually, run this to push fixes to Jira.

move – Move Issue to New Status

imdone move [<ISSUE_KEY>] [<STATUS>]

Alias: mv

Moves a Jira issue to a new status by performing a transition. If arguments are not provided, the command will prompt for them interactively.

When moving an issue to "Done" status, the resolution field can be set automatically or interactively.

Arguments:

• ISSUE_KEY - The Jira issue key (e.g., PROJ-123)
• STATUS - The target status name (case-insensitive)

Options:

• -f, --format <format> - Output format: json, yaml, csv, text (default: text)
• -r, --resolution <resolution> - Set custom resolution when moving to Done (e.g., "Fixed", "Won't Do")
• --no-resolution - Skip setting resolution even when moving to Done
• -p, --prompt-resolution - Interactively select resolution from available options

Resolution Behavior:

• By default, moving to "Done" automatically sets resolution to "Done"
• Existing resolutions are never overwritten
• Use --prompt-resolution to see all available resolutions and choose interactively
• Use --no-resolution to skip resolution setting entirely

Examples:

# Move issue with specified arguments (auto-sets resolution to "Done")
imdone move PROJ-123 "Done"

# Move issue with custom resolution
imdone move PROJ-123 "Done" --resolution "Fixed"

# Interactive resolution selection
imdone move PROJ-123 "Done" --prompt-resolution

# Move to Done without setting resolution
imdone move PROJ-123 "Done" --no-resolution

# Move issue and output in JSON format
imdone move PROJ-123 "In Progress" --format json

# Interactive mode - prompts for missing arguments
imdone move

# Prompt for status only
imdone move PROJ-123

The command automatically discovers available transitions for the issue and provides an interactive selection if the specified status is not valid.

lint – Lint Todo Comments

imdone lint

Checks and fixes formatting issues for compatibility with Jira.

reset – Reset Local Project State

imdone reset

Options:

• -f, --format <format> - Output format: json, yaml, csv, text (default: text)

Removes Jira integration state and pulls fresh data from Jira.

clean – Clean Project Data

imdone clean

Removes temporary files and data from the project without affecting the core configuration.

destroy – Remove Integration

imdone destroy

Deletes the config and backlog folder. Prompts for confirmation first.

license – Manage License

imdone license

Options:

• --token
• --show

Examples:

imdone license --token <your-token>
imdone license --show

show – Show Issue Details

imdone show [ISSUE_KEY]

Alias: s

Displays detailed information for a specific Jira issue including description, status, comments, and other fields. If no issue key is provided, you'll be prompted to search and select from existing issues.

Options:

• -f, --format <format> - Output format: json, yaml, csv, text (default: text)

Examples:

# Interactive mode - search and select issue
imdone show

# Default text format - markdown-like output
imdone show PROJ-123

# Text format (explicit)
imdone show PROJ-123 --format text
imdone show PROJ-123 -f text

# JSON format - structured data for automation
imdone show PROJ-123 --format json

# YAML format - preserves Jira markup and metadata
imdone show PROJ-123 --format yaml

# CSV format - tabular data
imdone show PROJ-123 --format csv

# Interactive mode with different format
imdone show --format json

list – Show Issues from Your Provider

imdone list

Alias: ls

Lists all issues from your configured provider (Jira or GitHub). Uses Unix ls-style flags for familiar terminal behavior.

Display Options:

• -l - Long format with detailed issue information (status, assignee, type)
• -1 - One issue per line (compact: KEY + PATH)
• -t - Sort by modification time (most recent first)
• -r - Reverse sort order
• Default format shows compact listing (KEY + PATH per line)
• Favorited issues show a ★ indicator in all views

Filter and Output Options:

• --fav, --favorites - Show only favorited issues (see imdone favorite)
• --limit <number> - Limit the number of tasks displayed (default: 0, no limit)
• -f, --format <format> - Output format: json, yaml, csv, text (default: text)
• -q, --query <query> - Override default query (JQL for Jira, GitHub search for GitHub)
• -v, --verbose - Show the query being used

Examples:

# Compact listing (default) - shows KEY and PATH
imdone list

# Long format with details (table view)
imdone ls -l

# Sort by time, most recent first
imdone ls -t

# Long format, sorted by time
imdone ls -lt

# Reverse the sort order (oldest first)
imdone ls -ltr

# One issue per line (same as default compact format)
imdone ls -1

# Limit to 10 most recent issues
imdone list -t --limit 10

# Show only favorited issues
imdone list --favorites
imdone ls --fav

# Favorites in long format, sorted by time
imdone ls --fav -lt

# List issues in JSON format
imdone list --format json

# List limited issues in CSV format
imdone list --limit 5 --format csv

# === Jira Examples ===

# List issues assigned to current user using custom JQL
imdone list -q "project = PROJ AND assignee = currentUser()"

# List issues in specific status with verbose output
imdone list -q "project = PROJ AND status = 'In Progress'" --verbose

# List issues from multiple projects
imdone list -q "project IN ('PROJ1', 'PROJ2') AND status != 'Done'"

# List high priority issues only
imdone list -q "project = PROJ AND priority IN ('High', 'Highest')"

# List issues with specific labels
imdone list -q "project = PROJ AND labels = 'urgent'"

# List issues from current sprint
imdone list -q "project = PROJ AND sprint in openSprints()"

# List recent issues (created in last 7 days)
imdone list -q "project = PROJ AND created >= -7d"

# === GitHub Examples ===

# List open issues assigned to you
imdone list -q "assignee:@me is:open"

# List issues with specific label
imdone list -q "label:bug is:open"

# List issues in a milestone
imdone list -q "milestone:v1.0 is:open"

# List closed issues
imdone list -q "is:closed"

# Combine multiple filters
imdone list -q "assignee:@me label:enhancement is:open"

Query Language Support:

The -q, --query option allows you to override your default query configuration with custom queries. This gives you flexibility to view specific subsets of issues without modifying your project configuration.

For Jira (JQL - Jira Query Language):

• JQL queries are validated before execution
• Must include a project specification (e.g., "project = PROJ")
• Provides helpful error messages with examples if validation fails
• Automatically suggests using configured project keys

Common JQL Patterns:

• project = KEY AND assignee = currentUser() - Issues assigned to you
• project = KEY AND status IN ("To Do", "In Progress") - Issues in specific statuses
• project = KEY AND sprint in openSprints() - Current sprint issues
• project = KEY AND fixVersion = "1.0.0" - Issues for specific version
• project = KEY AND created >= -7d - Recent issues
• project = KEY AND labels = "label-name" - Issues with specific labels

For GitHub (GitHub Search Syntax):

• Uses GitHub's search query syntax
• Supports: is:open, is:closed, assignee:username, assignee:@me, label:name, milestone:name
• No validation required (passed directly to GitHub API)

Common GitHub Query Patterns:

• assignee:@me is:open - Your open issues (note: @me is automatically resolved to your username)
• is:closed - All closed issues
• label:bug is:open - Open bugs
• milestone:v1.0 is:open - Open issues in milestone v1.0
• assignee:username label:enhancement - Enhancement issues assigned to specific user

Note: When using custom queries, the command fetches matching issues from your provider and then filters for those that exist in your local project. Use --verbose to see the exact query being executed.

favorite – Mark Issues as Favorites

imdone favorite [ISSUE_KEY]

Alias: f

Mark issues as favorites for quick access when working with many issues in your current sprint. Favorites are stored locally in .imdone/favorites.yml and are personal to your workspace.

Arguments:

• [ISSUE_KEY] - Issue key to favorite (e.g., PROJ-123 for Jira, 42 for GitHub)

Options:

• -r, --remove - Remove issue from favorites

Examples:

# Mark issue as favorite
imdone favorite PROJ-123

# Interactive mode - search and select from available issues
imdone favorite

# Remove issue from favorites
imdone favorite PROJ-123 --remove
imdone favorite PROJ-123 -r

# Interactive removal - search and select from favorited issues only
imdone favorite --remove

# List only your favorite issues
imdone ls --favorites
imdone ls --fav

# Combine with other ls flags
imdone ls --fav -l      # Long format, favorites only
imdone ls --fav -t      # Favorites sorted by time

How it works:

1. Mark as favorite: Validates the issue exists in your current sprint and adds it to your favorites list
2. Visual indicator: Favorited issues show a ★ indicator in all list views
3. Filter favorites: Use imdone ls --favorites to see only your favorited issues
4. Personal workspace: Favorites are stored in .imdone/favorites.yml (git-ignored) and don't sync across team members

When to use:

• Working on 2-3 specific issues among many in current sprint
• Quickly filtering to your most important work items
• Reducing navigation overhead in large sprints

Provider Support:

• Jira: Use project keys like PROJ-123
• GitHub: Use issue numbers like 42

log – View Jira Changelog

imdone log [<ISSUE_KEY>] [--stats]

Shows changelog for an issue, with optional statistics. If no issue key is provided, you'll be prompted to search and select from existing issues.

Arguments:

• ISSUE_KEY - The Jira issue key (optional)

Options:

• --stats - Show statistics for the changelog
• -f, --format <format> - Output format: json, yaml, csv, text (default: text)

Examples:

# Show changelog for specific issue
imdone log PROJ-123

# Show changelog statistics for specific issue  
imdone log PROJ-123 --stats

# Show changelog in JSON format
imdone log PROJ-123 --format json

# Show changelog statistics in YAML format
imdone log PROJ-123 --stats --format yaml

# Interactive mode - search and select issue
imdone log

# Interactive mode with statistics
imdone log --stats

test – Test Configuration

imdone test

Validates connection and permission setup.

pause – Pause Desktop Watcher

imdone pause

Pauses the imdone desktop watcher by creating a .imdonepause file in the backlog directory. This prevents conflicts between CLI operations and the desktop application.

When to use:

• Before running extended CLI operations
• When you want to prevent desktop automatic syncing temporarily
• During manual conflict resolution

Note: All imdone-cli commands automatically pause the watcher during execution and resume when complete.

resume – Resume Desktop Watcher

imdone resume

Resumes the imdone desktop watcher by removing the .imdonepause file from the backlog directory.

When to use:

• After manually pausing the watcher
• If a CLI command was interrupted and didn't resume automatically

hooks – Git Hooks Management

Set up automatic imdone pull after git pull and imdone push before git push

imdone hooks setup

Options:

• --force - Overwrite existing git hooks

This sets up git hooks that automatically synchronize your Jira issues with git operations:

• post-merge hook: Runs imdone pull after each successful git pull to fetch the latest Jira issues
• pre-push hook: Runs imdone push before each git push to ensure your local Jira changes are synchronized

Remove git hooks

imdone hooks remove

Removes git hooks that were set up by imdone-cli.

How it works:

• Creates post-merge and pre-push hooks in .git/hooks/
• The hooks detect if the current directory has imdone configuration
• post-merge: Automatically runs imdone pull after successful git merges (which happen during git pull)
• pre-push: Automatically runs imdone push before git push operations
• The pre-push hook will cancel the push if imdone push fails (use git push --no-verify to bypass)
• Only runs for actual merges, not rebases
• Gracefully handles cases where imdone-cli is not available

🐙 GitHub Integration

imdone-cli fully supports GitHub Issues as an alternative to Jira. This allows teams using GitHub to benefit from the same context-driven development workflow.

Supported Features

• imdone init with GitHub provider selection
• imdone pull to fetch GitHub issues into local markdown files
• imdone push to sync local changes back to GitHub
• imdone add to create new GitHub issues with template support
• imdone ls to list GitHub issues with custom queries
• imdone template to apply templates to GitHub issues
• Comment synchronization (via imdone pull and imdone push)
• Auto-detection of GitHub owner/repo from git remote origin
• Status mapping (open/closed → TODO/DOING/DONE)
• Label support (template tags automatically converted to labels)

Getting Started with GitHub

1. Initialize with GitHub:

   imdone init
   # Select "github" when prompted for provider

2. GitHub automatically detects your repository:

   • Owner and repo are extracted from your git remote origin URL
   • Supports both SSH and HTTPS remote URLs

3. Provide your GitHub Personal Access Token:

   • Create a token at: https://github.com/settings/tokens
   • Required scope: repo (full control of private repositories)
   • Token is stored securely in .env file

4. Pull your GitHub issues:

   imdone pull

GitHub-Specific Features

Query Syntax: GitHub uses a simplified query syntax (not JQL):

• is:open - Open issues
• is:closed - Closed issues
• label:bug - Issues with "bug" label
• milestone:v1.0 - Issues in "v1.0" milestone
• assignee:username - Issues assigned to specific user

Status Mapping: Configure in .imdone/config.yml:

settings:
  plugins:
    JiraPlugin:
      provider: github
      owner: your-org
      repo: your-repo
      statuses:
        - github: open
          list: TODO
        - github: in_progress
          list: DOING
        - github: closed
          list: DONE

Directory Structure: Same as Jira - each issue gets its own folder:

backlog/
├── current-sprint/
│   ├── 123-Fix_login_bug/
│   │   └── issue-123.md
│   └── 124-Add_dashboard/
│       └── issue-124.md

GitHub vs Jira Feature Comparison

| Feature | Jira | GitHub | |---------|------|--------| | Pull issues | ✅ | ✅ | | Push changes | ✅ | ✅ | | Comments | ✅ | ✅ | | Attachments | ✅ | N/A (GitHub embeds in markdown) | | Custom fields | ✅ | ❌ Not supported | | Sprints | ✅ | ❌ Use milestones | | Issue types | ✅ | ❌ Use labels | | Epics | ✅ | ❌ Use milestones |

Example Workflow

# 1. Initialize with GitHub
imdone init

# 2. Pull open issues
imdone pull

# 3. Edit issues in your editor
code backlog/current-sprint/

# 4. Sync changes
imdone push

📝 Markdown Formatting Guide

The imdone-cli includes automatic markdown formatting to ensure consistency across your project files. When you run imdone lint or imdone push, the following formatting rules are applied:

Formatting Rules

List Indentation

• All lists: Uses 4 spaces per indentation level for consistent formatting
• Ordered lists: Uses 4 spaces per indentation level
• Unordered lists: Uses 4 spaces per indentation level
• Mixed lists: All nested lists maintain the 4-space indentation standard
• Inconsistent indentation will be automatically fixed

Example of proper list formatting:

1. First ordered item
    - First unordered subitem (4 spaces)
        - Nested unordered item (8 spaces)
            - Deeper nested item (12 spaces)
2. Second ordered item
    - Another unordered subitem (4 spaces)

Code Blocks

• All code blocks must use fenced style with triple backticks (```)
• Code block indentation is normalized:
  • Fence markers (```) are moved to the left margin
  • Content within code blocks is reduced the same number of spaces as the fence indentation

Emphasis and Strong Styling

• Emphasis (italics): Use asterisks *like this* instead of underscores
• Strong (bold): Use double asterisks **like this** instead of underscores

Rules Not Enforced

• Line length: No maximum line length is enforced
• Bare URLs: URLs without formatting are allowed
• Trailing punctuation: Headings can end with punctuation marks

Additional markdownlint Rules

All default markdownlint rules are applied except for the overrides listed above. These include:

• Consistent heading styles
• Proper spacing
• List formatting
• And many other standard markdown best practices

How Violations Are Fixed

When you run imdone lint or as part of imdone push:

1. List indentation is automatically fixed
2. Code block indentation is normalized
3. markdownlint runs to fix remaining issues
4. All fixed content is saved back to your files

All fixes are applied automatically so you don't need to manually correct formatting issues. This ensures that markdown files remain consistently formatted across your project and compatible with Jira integration.

📖 Detailed Documentation

Working with Comments

You can add comments to issues directly from your markdown files. Comments are automatically synchronized when you run imdone push.

How to add a comment:

1. Open the comments-<ISSUE_KEY>.md file for the issue you want to comment on
   • Jira: comments-SCRUM-31.md
   • GitHub: comments-1.md (issue number)
2. Add your comment in markdown format between the first line and the first --- separator
3. Run imdone push to sync the comment to your provider

Example (Jira):

# #TODO Comments: SCRUM-31 Enhance markdown to JIRA conversion

This is my new comment! I can use **bold**, _italic_, and other markdown formatting.

The comment supports multiple lines and will be converted to Jira markup automatically.

---

### Comment 10173 by Jesse Piascik (jpiascik) on 2025-07-22T08:57:41.151-0400

Here's another comment

---

Example (GitHub):

# #TODO Comments: 1 Test issue

This is my new comment! I can use **bold**, _italic_, and other markdown formatting.

GitHub uses markdown natively, so no conversion is needed.

---

### Comment 3832629667 by piascikj (piascikj) on 2026-02-02T02:48:59Z

Here's another comment

---

After running imdone push, your comment will be posted to the issue and the file will be updated to prevent duplicate posting.

Notes:

• Comments use markdown formatting
• Jira: Markdown is automatically converted to Jira markup
• GitHub: Markdown is used natively (no conversion)
• Only add content between the title line and the first --- separator

Requiring Comments for Tasks

You can enforce that certain tasks must have a comment before they can be pushed to your provider by adding commentRequired:true to the task's metadata.

Example task with required comment (Jira):

# #TODO Fix critical login bug

This task will require a comment before it can be pushed.

<!--
jira:PROJ-123
commentRequired:true
-->

Example task with required comment (GitHub):

# #TODO Fix critical login bug

This task will require a comment before it can be pushed.

<!--
github:1
commentRequired:true
-->

How it works:

1. When you run imdone push, the CLI checks if any tasks have commentRequired:true in their metadata
2. If a required comment is missing, you'll be prompted to enter one:

   Comment required for task "Fix critical login bug" (PROJ-123): 

3. The comment is automatically added to the corresponding comments-PROJ-123.md file
4. The push operation continues normally, syncing both the task and the new comment to Jira

When to use:

• Critical bugs that need explanation
• Complex features requiring documentation
• Tasks that affect multiple team members
• Any work item that benefits from context or reasoning

Working with Attachments

Imdone CLI automatically synchronizes attachments between Jira and your local project, making it easy to access files, images, and documents related to your issues without switching to the browser.

Automatic Download During Pull:

When you run imdone pull, all attachments from Jira issues are automatically downloaded to local attachments/ folders within each issue directory:

current-sprint/
├── PROJ-123-Fix_login_bug/
│   ├── attachments/
│   │   ├── error-screenshot.png
│   │   ├── debug-log.txt
│   │   └── .metadata.yml
│   ├── comments-PROJ-123.md
│   └── issue-PROJ-123.md

What gets downloaded:

• All attachment types: images, documents, logs, screenshots, etc.
• Original filenames are preserved
• File metadata is tracked in .metadata.yml for efficient synchronization
• Only new or changed attachments are downloaded on subsequent pulls

Attachment Features:

1. Intelligent Sync: Only downloads attachments that are new or have changed since the last pull
2. Size Validation: Verifies downloaded files match expected sizes from Jira
3. Metadata Tracking: Maintains local metadata to avoid unnecessary re-downloads
4. Error Handling: Gracefully handles download failures without stopping the pull process
5. Cleanup: Automatically removes local attachments that have been deleted from Jira

Accessing Attachments:

Once downloaded, attachments are available in your local file system:

• View images directly in your IDE or file explorer
• Open documents with your preferred applications
• Include attachment paths in documentation or code comments
• Reference attachments in markdown files using relative paths

Editing Attachments Locally:

You can add, modify, delete, or rename attachments directly in your local file system. When you run imdone push, these changes are automatically synchronized back to Jira:

1. Add a new attachment: Copy a file into the issue's attachments/ folder

   • imdone push will upload the new file to Jira
   • The file will be tracked in .metadata.yml after upload

2. Modify an attachment: Edit the file locally (e.g., update a screenshot, revise a document)

   • imdone push will upload the modified file as a new version
   • The old version is automatically deleted from Jira
   • Safety: If upload fails, the old version is preserved in Jira

3. Delete an attachment: Remove the file from the attachments/ folder

   • imdone push will delete the attachment from Jira
   • Note: If the attachment still exists in Jira, imdone pull will re-download it unless you push first

4. Rename an attachment: Rename the file in the attachments/ folder

   • imdone push treats this as: delete old file + upload new file
   • The old attachment is removed from Jira
   • The renamed file is uploaded as a new attachment

Example Workflows:

# Add a new attachment
imdone pull
cp ~/Desktop/architecture-diagram.png backlog/current-sprint/PROJ-123/attachments/
imdone push
# ✓ Added: PROJ-123/architecture-diagram.png (256KB)

# Modify an existing attachment
imdone pull
open backlog/current-sprint/PROJ-123/attachments/screenshot.png
# (make your edits and save)
imdone push
# ✓ Updated: PROJ-123/screenshot.png (125KB)

# Delete an attachment
imdone pull
rm backlog/current-sprint/PROJ-123/attachments/old-file.pdf
imdone push
# ✓ Deleted: PROJ-123/old-file.pdf

# Rename an attachment
imdone pull
cd backlog/current-sprint/PROJ-123/attachments/
mv draft-design.png final-design.png
cd -
imdone push
# ✓ Renamed: PROJ-123/draft-design.png → final-design.png

Example Directory Structure:

backlog/current-sprint/
├── SCRUM-31-Enhance_markdown_conversion/
│   ├── attachments/
│   │   ├── my-profile-image.jpeg          # Downloaded from Jira
│   │   ├── requirements-document.pdf      # Downloaded from Jira
│   │   └── .metadata.yml                  # Tracks sync status
│   ├── comments-SCRUM-31.md
│   └── issue-SCRUM-31.md

Technical Notes:

• Attachments are downloaded to issue-specific folders to avoid conflicts
• The .metadata.yml file tracks download status and shouldn't be manually edited
• Attachment downloads respect your configured backlogDir from .imdone-cli.yml
• Large attachments are handled efficiently with automatic retry on failures
• HTTP redirects are properly handled for secure Jira attachment URLs
• Safety mechanism: When modifying attachments, the new version is uploaded first, and the old version is only deleted if the upload succeeds. This prevents data loss in case of network failures or upload errors.

Customizing Your JQL Query

You can customize which Jira issues are pulled by modifying the JQL (Jira Query Language) in your project configuration:

Location: .imdone/config.yml

plugins:
  imdone-jira:
    jql: 'project = "YOUR-PROJECT" AND status != Done ORDER BY rank ASC'

Common JQL examples:

# Pull only issues assigned to you
jql: 'project = "PROJ" AND assignee = currentUser() AND status != Done ORDER BY rank ASC'

# Pull issues from specific sprint
jql: 'project = "PROJ" AND sprint in openSprints() ORDER BY rank ASC'

# Pull issues by labels
jql: 'project = "PROJ" AND labels in ("frontend", "backend") ORDER BY rank ASC'

# Pull issues from multiple projects
jql: 'project in ("PROJ1", "PROJ2") AND status != Done ORDER BY rank ASC'

# Pull only high priority issues
jql: 'project = "PROJ" AND priority in ("High", "Highest") ORDER BY rank ASC'

Tips:

• Use Jira's Query Builder in the web interface to test your JQL before adding it to config
• The ORDER BY rank ASC clause ensures issues appear in your backlog priority order
• After changing JQL, run imdone reset to refresh your local issues with the new query
• You can use Jira functions like currentUser(), openSprints(), and now()

⑂ imdone-cli and Git

Imdone CLI uses git to make it easier for the rest of your team to get the project configured. Git is also used to track changes to your backlog files, so you can resolve conflicts and easily revert to previous versions if needed.

In most cases, you should let imdone-cli handle Git operations for you. It's designed to commit and sync changes safely so you can stay focused on your work.

If you run into a Git conflict, just resolve it in your editor, then run imdone merge.

Automatic Branch Switching

To prevent accidental commits to the shared default branch (main), imdone-cli automatically manages branches in your backlog repository:

• Working Branch: All backlog modifications happen on the imdone-work branch
• Automatic Creation: The imdone-work branch is created automatically on first use
• Seamless Switching: If you're on main, commands like pull, push, add, update, merge, move, and reset will automatically switch to imdone-work
• Visual Feedback: You'll see a message when the branch switch happens: Switched to working branch 'imdone-work'

Special Cases:

• imdone init and imdone clone commit initial setup to main branch first, then subsequent operations automatically switch to imdone-work
• This ensures the foundational repository structure lives on the shared branch while all work happens on your working branch

Benefits:

• Prevents merge conflicts when multiple team members work simultaneously
• Keeps the default branch clean and stable
• Makes collaboration smoother and safer

📎 Attachment Versioning

imdone-cli handles attachment modifications safely to avoid permission errors when working with files created by other team members.

How It Works

When you modify an attachment that was created by another user:

• A new version is uploaded to Jira (no 403 errors)
• The old version is preserved in Jira (not deleted)
• Your local filesystem only keeps the current version
• Metadata tracks all versions for reference

Multiple Versions

If multiple team members modify the same attachment:

• Each upload creates a new version in Jira
• All versions are visible in the Jira UI
• On pull, only the most recent version is downloaded locally
• Metadata (.metadata.yml) tracks all version IDs and creation dates

Deleted and Renamed Attachments

Team Sync via Issue Comments:

When you delete or rename an attachment, a machine-readable comment is posted to the Jira issue. This ensures all team members automatically stay in sync:

When you delete an attachment locally:

rm attachments/old-doc.pdf
imdone push

• The file is removed from your local filesystem
• The attachment remains in Jira (no delete attempt - avoids 403 errors)
• A comment is posted to Jira: "Action: deleted, Filename: old-doc.pdf, Attachment ID: 12345"
• Added to your local ignored list (won't be re-downloaded on pull)
• All team members automatically sync this deletion on their next pull
• They won't re-download the deleted file

When you rename an attachment:

mv attachments/doc.pdf attachments/doc-v2.pdf
imdone push

• New attachment doc-v2.pdf is uploaded to Jira
• Old attachment doc.pdf remains in Jira
• A comment is posted: "Action: renamed, Old filename: doc.pdf, New filename: doc-v2.pdf"
• Old name added to your local ignored list
• All team members automatically skip the old filename on their next pull

Automatic Synchronization:

When any team member runs imdone pull:

1. Comments are parsed for attachment changes
2. Deleted/renamed files are added to their local ignored list
3. Only current attachments are downloaded
4. Everyone stays in sync automatically - no manual cleanup needed!

Manual Cleanup

Old versions in Jira are not automatically deleted. This prevents:

• 403 Unauthorized errors (no delete permission needed)
• Accidental data loss
• Team conflicts over attachment ownership

To clean up old versions:

• Jira users can manually delete old attachment versions from the Jira UI
• Team members can delete local files they don't need

Metadata Format

Attachments are tracked in attachments/.metadata.yml with a filename-keyed structure:

attachments:
  document.pdf:
    current: "12346"  # Most recent version ID
    versions:
      - id: "12346"
        filename: "document.pdf"
        size: 1500
        created: "2025-01-16T14:00:00Z"
        author:
          displayName: "User B"
          accountId: "..."
      - id: "12345"
        filename: "document.pdf"
        size: 1000
        created: "2025-01-15T10:00:00Z"
        author:
          displayName: "User A"
          accountId: "..."
ignored:
  - id: "12347"
    filename: "old-file.png"
    reason: "deleted"
    author: "[email protected]"
    timestamp: "2025-02-25T10:00:00Z"

Auto-migration: Old metadata formats are automatically migrated to the new format on first use. No data loss occurs during migration.

🪲 Troubleshooting

Invalid License

Check your token:

imdone license --show

Jira Connection Issues

Ensure:

• Jira URL is correct
• API token is valid
• You have permissions

Branch Issues

Stuck on the wrong branch:

If you find yourself on the main branch in your backlog directory, just run any imdone command and it will automatically switch you to imdone-work:

cd backlog
git branch  # Shows you're on 'main'
imdone pull  # Automatically switches to 'imdone-work' and continues

Want to see which branch you're on:

cd backlog
git branch

The current branch will be marked with an asterisk (*).

Merge conflicts:

If you encounter merge conflicts in your backlog repository:

1. Resolve conflicts in your editor
2. Stage the resolved files: git add .
3. Run: imdone merge

The automatic branch switching prevents most conflicts, but if multiple people work on the same issue simultaneously, conflicts can still occur.

Debug Mode

imdone-debug pull > debug.log

Use for support diagnostics.