Sync Jira Issues Directly to Your IDE
Are you tired of constantly switching between your IDE and Jira? What if I told you that you could pull your Jira backlog directly into your development environment and work with issues as markdown files?
In this comprehensive guide, I'll walk you through the imdone pull command and show you how to transform your Jira workflow forever.
What is Imdone CLI?
Imdone CLI is a powerful tool that bridges the gap between project management and development. It allows you to sync Jira issues directly into your local environment as markdown files, enabling you to work on your backlog without ever leaving your editor.
Getting Started: Your First Pull
After initializing your project with Imdone CLI, running your first imdone pull is magical. Here's what happens:
imdone pull
This command:
- Connects to your Jira instance
- Pulls issues based on your configured JQL query
- Creates a local
backlog/folder structure - Converts issues to markdown format for easy editing
Understanding the Folder Structure
Once you run imdone pull, you'll see a new folder structure:
backlog/
├── current-sprint/
│ └── [ISSUE-KEY]-[ISSUE-SUMMARY]/
│ ├── attachments/ # File attachments
│ ├── comments-[ISSUE-KEY].md # Issue comments
│ └── issue-[ISSUE-KEY].md # Main issue content
└── .imdone/
└── config.yml # JQL configuration
Each issue gets its own folder containing:
- issue.md - The main issue content in markdown format
- comments.md - All issue comments in a single file
- attachments/ - Folder for any file attachments
Working with Issues Locally
Editing Issue Content
Issues are stored as clean markdown files that you can edit directly in your IDE. Need to update the description? Just edit the markdown. Want to check off acceptance criteria? Add an x to the checkbox.
Adding Comments
To add a comment, simply update the comments file:
<!-- Replace this comment with your new comment and push -->
Replace the HTML comment with your actual comment and push the changes back to Jira.
Managing Attachments
Add files to the attachments/ folder and they'll be synced to Jira on your next push (with a license).
Configuring Your JQL Query
The power of imdone pull lies in its flexibility. You control which issues get pulled through JQL (Jira Query Language) configuration.
Edit your configuration at backlog/.imdone/config.yml:
jql: "project = DEMO AND assignee = currentUser()"
Some useful JQL examples:
-
Personal issues:
assignee = currentUser() -
Current sprint:
sprint in openSprints() -
Specific project:
project = "MY-PROJECT" -
Issue types:
type in (Story, Bug) -
Status filtering:
status = "To Do"
Handling Local Changes and Pulls
Here's where Imdone really shines. When you have local changes and run imdone pull, the tool automatically:
- Stashes your changes to preserve your work
- Pulls the latest from Jira to get updates
- Applies your changes back on top of the updates
If there are conflicts, Imdone will prompt you to run:
imdone merge
This handles merge conflicts gracefully, ensuring you never lose work.
Git Integration Behind the Scenes
Imdone creates a separate Git repository in your backlog/ folder to handle versioning and conflict resolution. You can inspect what's happening:
cd backlog/
git log
You'll see commits for:
- Initial pulls from Jira
- Subsequent syncs
- Your pushes back to Jira
Free vs Licensed Features
Free Tier (Perfect for trying it out):
- Pull unlimited issues
- Push up to 5 issues
- Full issue content editing
Licensed Features (For teams and heavy usage):
- Unlimited push operations
- Comments synchronization
- Attachments synchronization
- Get these features at imdone.io/plans
Pro Tips for Success
1. Keep JQL Focused
If you're on the free tier, keep your JQL query focused to stay under the 5-issue push limit:
jql: "assignee = currentUser() AND status = 'In Progress'"
2. Use Clean Commands
Reset your backlog when testing configurations:
imdone clean # Empties the backlog folder
imdone pull # Fresh pull from Jira
3. Monitor Git History
Check what's happening behind the scenes:
cd backlog/
git log --oneline
4. Customize for Your Workflow
Adjust your JQL in .imdone/config.yml based on your team's needs:
- Sprint-focused queries for agile teams
- Assignee-based queries for individual workflow
- Priority-based queries for critical work
Why This Changes Everything
The real power of Imdone isn't just convenience—it's about maintaining context and ensuring everyone stays aligned, including your AI coding assistants.
The Context Problem
In traditional workflows, context gets fragmented across multiple tools:
- Requirements live in Jira
- Code lives in your IDE
- Discussions happen in Slack or comments
- Documentation exists separately
This fragmentation leads to:
- Lost context when switching between tools
- Misaligned team members working from outdated information
- AI agents that can't see the full picture of what you're building
- Knowledge silos where important details get buried
The Imdone Solution: Context-Driven Development
With Imdone, everything lives together in your repository:
🎯 Unified Context
- Issues, requirements, and code in one place
- AI agents can read both your code AND the business requirements
- No more "What was this feature supposed to do again?"
👥 Team Alignment
- Everyone works from the same markdown files
- Changes to requirements are tracked in Git
- Pull requests include both code changes AND requirement updates
- New team members onboard faster with everything in the repo
🤖 AI Agent Empowerment
- Your AI coding assistant can read issue descriptions while writing code
- Acceptance criteria become available during code review
- AI can suggest code that actually matches the business requirements
- Context stays preserved across entire development sessions
📚 Knowledge Preservation
- All project context lives in version control
- Historical decisions and discussions are preserved
- Requirements evolution is tracked alongside code changes
- Nothing gets lost when team members leave
Before vs After Imdone:
Before:
- "Wait, what was the exact requirement for this feature?"
- AI agents coding blindly without business context
- Team members working from different versions of requirements
- Context switching kills productivity and focus
After:
- Requirements and code live side-by-side
- AI agents understand WHAT you're building, not just HOW
- Entire team works from single source of truth
- Context flows naturally from planning to coding to deployment
Real-World Workflow Example
Here's how a typical development session looks:
# Start your day
imdone pull
# See what's in your backlog
ls backlog/current-sprint/
# Work on an issue
# Edit: backlog/current-sprint/DEMO-123-Add-User-Auth/issue.md
# Mark tasks complete with markdown checkboxes
- [x] Set up authentication routes
- [x] Add login form validation
- [ ] Write unit tests
# Push changes back to Jira
imdone push
Getting Started Today
- Install Imdone CLI from the documentation
-
Initialize your project with
imdone init - Configure your JQL for the issues you want to work with
-
Run your first pull with
imdone pull - Start working with issues directly in your IDE!
What's Next?
The future of development is context-driven, and tools like Imdone are making it possible to blur the lines between project management and coding. Give it a try and transform your workflow today!
Have you tried Imdone CLI? Share your experience in the comments below! And if you found this helpful, consider following for more developer productivity content.
Top comments (0)