imdone-cli docs
Command reference
Full command reference generated from the README.
Commands
📋 Output Formats: Many commands support the
-f, --formatoption to change output format. Available formats are:json,yaml,csv,text(default).
Command index
init- Initialize Issue Tracking Integrationclone- Clone Remote Backlog Repositoryupdate- Update imdone-cli Confighdd- Launch A Coding Agent With HDD Contextpull- Pull Issues from Providerpush- Push Changes to Providerstatus- Show Pending Changesadd- Create New Issuetemplate- Apply Template to Existing Issuemerge- Resolve Conflictsmove- Move Issue to New Statuslint- Lint Todo Commentsreset- Reset Local Project Stateclean- Clean Project Datadestroy- Remove Integrationlicense- Manage Licenseshow- Show Local Issue Contextlist- List Local Issuesfavorite- Mark Issues as Favoriteslog- View Issue Changelogtest- Test Configurationpause- Pause Desktop Watcherresume- Resume Desktop Watcherhooks- Git Hooks Management
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:jiraorgithub--force- Force initialization even if.imdone-cli.ymlexists in an ancestor directory
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-url- GitHub Enterprise URL (for example,https://github.mycompany.com)--github-owner- GitHub repository owner (auto-detected from git remote when in a git repo)--github-repo- GitHub repository name (auto-detected from git remote when in a git repo)--github-token- GitHub Personal Access Token--gql- GitHub issue query (for example,is:issue state:open)
GitHub Notes:
imdone pullfetches issues, comments, and attachments from GitHubimdone pushsyncs issue content, labels, comments, and attachments (add/modify/delete/rename)imdone addfully supports creating GitHub issues- GitHub owner and repo are auto-detected from your git remote origin URL
- During
imdone init, the GitHub repository prompt accepts HTTPS and Git-style SSH repository inputs such ashttps://github.com/owner/repo,git@github.com:owner/repo.git,ssh://git@github.com/owner/repo.git, andgit+ssh://git@github.com/owner/repo.git - The GitHub repository prompt now shows accepted repository examples directly in the prompt, and invalid input repeats those examples in the validation message
- Token guidance: classic tokens need
repo; fine-grained tokens need repositoryContents: Read and write,Issues: Read and write, andPull requests: Read and write
clone – Clone Remote Backlog Repository
imdone clone
Options:
--remote-url--backlog-dir--github-owner--github-repo--github-token
Clones a remote backlog repo for onboarding or setting up a new local workspace. After the backlog is cloned locally, imdone clone reads the cloned config and prompts only for any missing provider-specific setup values that are still needed, such as GitHub owner, repo, or token.
If the cloned .imdone-cli.yml is already configured for GitHub, imdone clone now preserves that provider instead of falling back to Jira prompts. GitHub-backed clones only ask for missing owner, repo, and token values after clone. Existing cloned config values and CLI flags suppress redundant prompts, and gql stays in the cloned config rather than being re-prompted.
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
hdd – Launch A Coding Agent With HDD Context
imdone hdd [issueKey]
imdone hdd --setup
Launch Codex or Claude with a startup prompt that tells the agent to use the bundled hypothesis-driven-development skill for the resolved story.
By default, imdone hdd:
- uses the explicit
issueKeyargument when provided - otherwise reuses the active HDD story from
backlog/.imdone/hdd-skill.yml - otherwise prompts for a story key
- reuses the saved default coding agent when available
- falls back to a pasteable HDD prompt when no supported coding agent is installed
Use --setup to force reselecting both the story key and coding agent instead of reusing the saved HDD launch context.
Options:
-s, --setup- Force issue-key and agent setup before launch
pull – Pull Issues from Provider
imdone pull
Alias: g
Options:
-f, --format <format>- Output format: json, yaml, csv, text (default: text)--jql [jql]- Jira only. Temporarily override the saved Jira query for this pull run only--gql [gql]- GitHub only. Temporarily override the saved GitHub query for this pull run only
Fetches issues, comments, and attachments from your configured provider, updates the local Markdown workspace, and restores local changes when needed.
For Jira-backed projects, you can use --jql to temporarily broaden or change the pull scope for one run without editing .imdone/config.yml. This is useful for backlog refinement when you want to pull a wider set of issues and then return to your normal default sync scope on the next plain imdone pull.
For GitHub-backed projects, you can use --gql to temporarily target a specific GitHub issue or pull-request slice for one run without changing the saved default GitHub query.
If the project is configured with both Jira and GitHub providers:
--jqlaffects only the Jira provider for that run--gqlaffects only the GitHub provider for that run- you can use both in the same
imdone pullcommand
What gets pulled:
- Issue content and metadata
- All comments (see Working with Comments)
- All attachments (see Working with Attachments)
- Status and field updates
Provider 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
- Attachments are downloaded from the dedicated
imdone-attachmentsbranch and linked locally - When an issue is newly pulled and already maps to the done list, it is created directly in the archive folder if archive is configured
Jira:
- Uses JQL queries for flexible filtering
- Sprint and epic integration
imdone pull --jql "<query>"temporarily replaces the saved Jira query for that run only, while still refreshing already-synced local Jira issues- In mixed Jira/GitHub projects,
--jqlaffects only the Jira provider’s pull for that run - When an issue is newly pulled and already maps to the done list, it is created directly in the archive folder if archive is configured
GitHub query override examples:
# Temporarily target one GitHub slice
imdone pull --gql 'is:pr state:open'
# Temporarily override both providers in the same run
imdone pull --jql 'project = "SCRUM" AND status != Done ORDER BY updated DESC' --gql 'is:pr state:open'
push – Push Changes to Provider
imdone push
imdone push PROJ-123
Alias: p
Pass an issue key or number to push one issue only. For example, imdone push SCRUM-335 syncs that issue and leaves unrelated local issue changes in your working tree.
Options:
--rewrite-repo-links- GitHub only. For touched issues, republish in-scope issue content and text attachments so local repo-relative markdown links are refreshed against the current source-repo web-link mapping
Lints, pulls, extracts updates, and syncs your local Markdown changes back to the provider. A plain imdone push processes pending provider-backed issue changes. imdone push <issueKey> scopes the pull, provider write, and local git commit to that issue.
What gets pushed:
- Issue content and metadata changes
- New comments (see Working with Comments)
- New and modified attachments (see Working with Attachments)
- Labels
- Provider workflow state when the issue’s local imdone list has an explicit status mapping
Provider Notes:
Jira:
- Validates markdown formatting for Jira compatibility
- Converts markdown to Jira markup automatically
- Applies mapped local-list changes as Jira workflow transitions when
.imdone/config.ymlhas a matchingstatuses[*].listandstatuses[*].jiraentry
GitHub:
- Uses markdown natively (no conversion needed)
- Applies mapped local-list changes by using native
open/closedstate mappings or configured GitHub status labels/tags - Attachments are uploaded to the dedicated
imdone-attachmentsbranch; local links are rewritten to the current attachment URL imdone push --rewrite-repo-linksexplicitly refreshes in-scope repo-relative markdown links in touched GitHub issue content and text attachments against the current source-repo web-link mapping, even when the touched content would not otherwise need republishing- GitHub attachment add, modify, delete, and rename operations update the branch-backed current set without writing an attachment ledger comment
💡 Pro Tip: Use
commentRequired:truein task metadata to enforce comments on critical issues before pushing.
status – Show Pending Changes
imdone status
Alias: st
Shows all files in your backlog directory that have local changes not yet pushed — tasks, comments, and attachments — grouped by operation type.
Output:
Changes in backlog/current-sprint (4 files):
Added:
attachment SCRUM-200 new-plan.md
Modified:
task SCRUM-123 issue-description.md
comment SCRUM-123 comments-SCRUM-123.md
Deleted:
attachment SCRUM-456 screenshot.png
Each line shows the kind (task, comment, or attachment), the issue key, and the filename. If the directory is clean, it prints Nothing to push — working directory is clean.
add – Create New Issue
imdone add
Alias: a
Creates a new Jira or GitHub issue either interactively or from provided options. The prompts adapt to the selected provider.
Options:
--provider [provider]- Provider to create the issue in (jiraorgithub)--project-key [projectKey]- Project key (e.g.,PROJfor Jira,owner/repofor 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)--list-sprints- Jira only. List active sprint names and IDs that can be used with--sprint-id, then exit without creating an issue--list-issue-types- Jira only. List available issue types that can be used with--issue-type, then exit without creating an issue--summary [summary]- Issue summary/title-f, --format <format>- Output format: json, yaml, csv, text (default: text)
Examples:
# Jira: Discover valid sprint IDs first
imdone add --project-key PROJ --list-sprints
# Jira: Discover valid issue types first
imdone add --project-key PROJ --list-issue-types
# 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):
- Template selection - Choose from available templates in
.imdone/templates - Project selection - Choose which project to create the issue in (only shown when multiple projects are configured)
- Issue type - Select issue type (Jira only - skipped for GitHub)
- Location - Choose current sprint or backlog (Jira only - skipped for GitHub)
- Summary - Enter the issue title/summary
Sprint discovery:
If you want to script issue creation into a specific Jira sprint, run imdone add --list-sprints first. It prints the active sprint names and IDs for the selected Jira project, so you can copy the correct value into --sprint-id without opening Jira.
Issue type discovery:
If you want to script issue creation with an exact Jira issue type, run imdone add --list-issue-types first. It prints the available issue types for the selected Jira project, so you can pass the exact value into --issue-type without guessing.
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
- When a template is selected, follow-up template files, provider updates, and local commits are scoped to the new issue so other local issue edits remain untouched
Templates:
If your project has templates in .imdone/templates, they are available during issue creation. Templates give you consistent starting structure, and tags in templates (for example #bug or #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 issue through an interactive guided flow or with explicit 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):
- Issue selection - Choose from available issues in current sprint
- Template selection - Choose from available templates in
.imdone/templates
What gets applied:
- Template metadata (tags, custom fields) is merged with existing metadata
- Provider refresh and push are scoped to the target issue. If the issue was just refreshed in the same command,
imdone templateskips a redundant second pull before pushing the template update.
Templates:
Templates are markdown files in .imdone/templates that provide consistent issue structure. Templates can reference existing issue content with ${markdown} to keep current content in place. 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.,storyortemplate_story)
- Template names can be specified with or without the
- 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:
- Create the
attachments/directory in the issue folder - Create
story.mdwith content from thestorytemplate - Create an empty
notes.mdfile - Create
test-plan.mdwith content from thetesttemplate
merge – Resolve Conflicts
imdone merge
After resolving conflicts manually, run this to push the resolved changes to your configured provider.
move – Move Issue to New Status
imdone move [<ISSUE_KEY>] [<STATUS>]
Alias: mv
Moves a Jira or GitHub issue to a new status by performing the provider-specific status change. 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 issue identifier (for example, JiraPROJ-123or a GitHub issue number)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--list-statuses- List valid statuses for the issue without changing it--list-transitions- Alias for--list-statuses
Resolution Behavior:
- By default, moving to “Done” automatically sets resolution to “Done”
- Existing resolutions are never overwritten
- Use
--prompt-resolutionto see all available resolutions and choose interactively - Use
--no-resolutionto 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
# List valid statuses without changing the issue
imdone move PROJ-123 --list-statuses
# List valid statuses in structured output
imdone move PROJ-123 --list-statuses --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. Use --list-statuses or --list-transitions when you want that discovery step without mutating the issue.
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-s, --show
Examples:
imdone license --token <your-token>
imdone license --show
imdone license -s
show – Show Local Issue Context
imdone show [ISSUE_KEY]
Alias: s
Shows the local shared context for one issue from your backlog repo. The default text output includes the issue title, status, tags, metadata, repo-relative paths for the issue and comments files, the attachments directory, and visible attachment filenames. 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)
Structured output:
jsonandyamlinclude the local issue-context fields for automation, includingkey,title,status,tags,meta,issueFile,commentsFile,attachmentsDir, andattachmentscsvflattens the same fields for shell and spreadsheet workflows
Notes:
- Paths are repo-relative, not absolute
- Missing comments or attachments are shown explicitly as
nonein text output andnull/ empty arrays in structured output
Examples:
# Interactive mode - search and select issue
imdone show
# Default text format - local shared context
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 – List Local Issues
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 (seeimdone 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>- Filter issues using imdone filter syntax (applied locally)
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
# Filter by status
imdone ls -q 'meta.status="In Progress"'
# Filter by assignee
imdone ls -q 'meta.assignedTo="username"'
# Filter by label/tag
imdone ls -q 'tag:bug'
# Filter open issues
imdone ls -q 'meta.status="open"'
# Filter by milestone
imdone ls -q 'meta.milestone="v1.0"'
# Filter blocked issues (Jira)
imdone ls -q 'meta.blocked=*'
# Combine filters
imdone ls -q 'meta.status="open" and tag:enhancement'
# Filter pull requests (GitHub)
imdone ls -q 'meta.isPullRequest=true'
imdone Filter Syntax:
The -q, --query option uses imdone’s filter syntax, applied locally against your synced issues. This single query language works across all providers (Jira, GitHub).
Learn more about imdone filter syntax
Common filter patterns:
meta.status="In Progress"- Filter by status valuemeta.assignedTo="username"- Filter by assigneemeta.milestone="v1.0"- Filter by milestone (GitHub)meta.blocked=*- Show blocked/flagged issues (Jira)tag:bug- Filter by tag/labelmeta.isPullRequest=true- Show only pull requests (GitHub)meta.status="open" tag:enhancement- Combine multiple filters
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-123for Jira,42for 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:
- Mark as favorite: Validates the issue exists in your current sprint and adds it to your favorites list
- Visual indicator: Favorited issues show a ★ indicator in all list views
- Filter favorites: Use
imdone ls --favoritesto see only your favorited issues - 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 Issue Changelog
imdone log [<ISSUE_KEY>] [--stats]
Shows changelog for a Jira or GitHub issue, with optional statistics. If no issue key is provided, you’ll be prompted to search and select from existing issues. In mixed-provider projects, the selected or supplied issue key is resolved against local issue metadata so the changelog request is sent to the correct provider adapter.
Arguments:
ISSUE_KEY- The issue identifier (optional). Use Jira keys likePROJ-123or GitHub issue numbers like42.
Options:
-s, --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 for a GitHub issue
imdone log 42
# 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 configured provider with git operations:
- post-merge hook: Runs
imdone pullafter each successfulgit pullto fetch the latest provider issues - pre-push hook: Runs
imdone pushbefore eachgit pushto ensure your local issue changes are synchronized
Remove git hooks
imdone hooks remove
Removes git hooks that were set up by imdone-cli.
How it works:
- Creates
post-mergeandpre-pushhooks in.git/hooks/ - The hooks detect if the current directory has imdone configuration
- post-merge: Automatically runs
imdone pullafter successful git merges (which happen duringgit pull) - pre-push: Automatically runs
imdone pushbeforegit pushoperations - The pre-push hook will cancel the push if
imdone pushfails (usegit push --no-verifyto bypass) - Only runs for actual merges, not rebases
- Gracefully handles cases where imdone-cli is not available