Command reference

Commands

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

Command index

• init - Initialize Issue Tracking Integration
• clone - Clone Remote Backlog Repository
• update - Update imdone-cli Config
• docs - Open imdone-cli Docs
• current - Show Or Set The Current Story
• ai - Launch A Coding Agent With Story Context
• hdd - Launch A Coding Agent With HDD Context
• note - Record A Local Issue Progress Note
• pull - Pull Issues from Provider
• push - Push Changes to Provider
• status - Show Pending Changes
• add - Create New Issue
• template - Apply Template to Existing Issue
• merge - Resolve Conflicts
• move - Move Issue to New Status
• lint - Lint Todo Comments
• reset - Reset Local Project State
• clean - Clean Project Data
• destroy - Remove Integration
• license - Manage License
• show - Show Local Issue Context
• list - List Local Issues
• workbench - Open The Local Issue Board
• favorite - Mark Issues as Favorites
• log - View Issue Changelog
• test - Test Configuration
• pause - Pause Desktop Watcher
• resume - Resume Desktop Watcher
• hooks - 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: jira or github
• --force - Force initialization even if .imdone-cli.yml exists in an ancestor directory
• --resumability-test - After the built-in pull, offer the guided picker for one local HDD Light resumability test

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

Jira Notes:

• Enterprise or self-hosted Jira instances that use Personal Access Tokens with Bearer auth should set JIRA_AUTH_BASIC=false in the backlog .env file.
• Jira-backed configs require issueType under settings.plugins.JiraPlugin; use the exact Jira issue type name such as Story, Task, or Bug.
• Generated configs write JQL as a YAML block scalar. If you hand-edit .imdone/config.yml, use jql: |- for queries with quotes, colons, or other punctuation.

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 pull fetches issues, comments, and attachments from GitHub
• imdone push syncs issue content, labels, comments, and attachments (add/modify/delete/rename)
• imdone add fully 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 as https://github.com/owner/repo, git@github.com:owner/repo.git, ssh://git@github.com/owner/repo.git, and git+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 repository Contents: Read and write, Issues: Read and write, and Pull 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
imdone update --format json

Alias: u

Refresh newer imdone-managed project files from origin/main, then refresh bundled imdone project files such as docs, skills, templates, and local support files. Explicit and automatic updates preserve the configured default directory and .imdone/config.personal.yml, so active story changes do not block maintenance. The command reports its mode, trigger, and changed file paths, or reports that no files changed. Run imdone pull separately when you want to sync Jira or GitHub issues.

Update also retires the old stock_story, stock_product_mindset_story, and stock_lean_story templates from existing projects. Imdone removes a legacy file only when its contents match a known bundled version. A file customized at one of those paths is preserved byte-for-byte and reported as customized in text and structured output.

After a successful imdone pull or imdone push, detected remote or bundled changes update automatically by default. To keep the confirmation prompt while developing imdone-cli, add this personal override:

# .imdone/config.personal.yml
settings:
  plugins:
    JiraPlugin:
      updateMode: prompt

The personal file overrides the complete settings.plugins.JiraPlugin subtree in memory, including values such as providers, statuses, queries, nested adapter settings, and updateMode. Plain objects merge recursively while personal arrays and scalar values replace shared values. Settings outside that subtree are ignored, personal values are not written into shared .imdone/config.yml, and the personal file is excluded from remote update and staging paths.

Options:

• --force - Force the update without prompting when imdone-cli is outdated
• --skip-merge - Skip remote project-file application and only copy bundled files
• -f, --format <format> - Output format: json, yaml, text

docs – Open imdone-cli Docs

imdone docs

Opens the public imdone-cli docs page in your default browser:

https://imdone.io/imdone-cli

current – Show Or Set The Current Story

imdone current
imdone current PROJ-123

Shows the active story stored in backlog/.imdone/agent-config.yml, including the story key and title. Use this before recording progress notes when you want to confirm which story imdone-backed agent workflows consider current.

With an issue key, imdone current <issueKey> validates that the issue exists locally before changing the active story. If no story is active, the stored story is stale, or the requested issue is not available locally, the command exits non-zero and tells you how to recover.

imdone current is the workflow-friendly way to inspect or change active-story context. Use imdone agent-config only when you need the lower-level JSON configuration surface.

The global current story is separate from an AI or HDD session story. Loading or redirecting a progress note for another story does not change global current; only an explicit imdone current <issueKey> command does.

ai – Launch A Coding Agent With Story Context

imdone ai [issueKey]
imdone ai --setup

Launch Codex or Claude with lightweight story context. Use this when you want an agent to read the local issue, comments, attachments, and progress notes, then wait for your next instruction without starting the full HDD workflow.

By default, imdone ai:

• uses the explicit issueKey argument when provided
• otherwise prompts for a story key, with the active story from backlog/.imdone/agent-config.yml preselected when available
• does not change the active story in backlog/.imdone/agent-config.yml
• reuses the saved default coding agent when available
• falls back to a pasteable story-context prompt when no supported coding agent is installed

Launch output shows the configured active story and points to imdone current <issueKey> when you need to correct story context before progress notes are recorded.

The generated context includes a session-story marker. Agents retain that story across note-only redirects and check pending changes only for that story before offering a targeted push.

imdone ai uses its trusted imdone-story-context:v1 marker to enable event-triggered progress-note capture for the retained story without a separate consent prompt. It still loads lightweight story context rather than starting HDD, and it does not change the global current story. Add an explicit no-capture instruction when you want the launched session to remain capture-off.

Use --setup to force reselecting both the story key and coding agent instead of reusing the saved lightweight AI launch context.

Options:

• -s, --setup - Force issue-key and agent setup before launch

The prompt tells the agent to wait for user instructions before assuming it should do more than read context, and to use imdone note for decisions, blockers, corrections, completed work, evidence, and next steps. Use imdone hdd when you want the full Hypothesis-Driven Development session contract.

hdd – Launch A Coding Agent With HDD Context

imdone hdd [issueKey]
imdone hdd --light [issueKey]
imdone hdd --light --resumability-test STORY-123
imdone hdd --setup
imdone hdd --preserve-global-current PROJ-123

Launch Codex or Claude after imdone best-effort ensures the public product-engineering@product-engineering plugin is installed at user scope for every detected supported agent. Before launch, imdone reports the installed version, target version, setup decision, and cleanup status for each agent. The startup prompt prefers product-engineering:hypothesis-driven-development from imdone/product-engineering; if setup fails, imdone warns you and launches with the bundled imdone:hypothesis-driven-development fallback still available. When anonymous analytics are enabled, the setup failure emits a sanitized event without prompt text, issue keys, paths, plugin inventory, or raw command output.

By default, imdone hdd:

• uses the explicit issueKey argument when provided
• otherwise reuses the active HDD story from backlog/.imdone/agent-config.yml
• otherwise prompts for a story key
• reuses the saved default coding agent when available
• leaves an already-installed public plugin unchanged and attempts user-level installation for every detected Codex and Claude CLI before launch
• falls back to a pasteable HDD prompt when no supported coding agent is installed

Use --light to start lightweight HDD directly for low-risk work. Without the flag, existing closing metadata selects the saved mode before the agent asks: full imdoneTemplate values or standalone #HDD-template select Full HDD; lightweight template values or #HDD-light-template select Lightweight HDD, including legacy stories that also carry the companion full tag. The mode prompt appears only when no reliable saved mode exists.

Use --resumability-test with the homepage experiment to enroll one explicitly selected story. The first launch records the enrollment in the ignored personal file backlog/.imdone/resumability-tests.personal.json and starts HDD without asking for an outcome. Running the explicit enrollment command again deliberately replaces that story’s prior local attempt and starts a fresh one; ordinary imdone hdd never resets it. In a later session, run ordinary imdone hdd and select the enrolled story; the CLI detects its private local enrollment and asks whether this is a genuine resumption after an interruption, handoff, or fresh session. Confirming records the resumption and starts the agent without an outcome question. On the following launch, the CLI asks one question about whether imdone made the story materially easier to resume. Choose Not yet to defer either check or Stop asking to end participation for that story.

The answer is saved locally before any network attempt. Existing anonymous-analytics consent controls whether the fixed experiment result is sent; story keys, story contents, repository names, paths, prompts, and email addresses are never included. Disabled analytics or a failed delivery never blocks the agent launch, and a failed delivery remains pending for a later retry without repeating the question.

Use --setup to force reselecting both the story key and coding agent instead of reusing the saved HDD launch context.

Use --preserve-global-current when the selected HDD story should stay in session memory without replacing the globally configured current story. Before a push reminder, HDD checks imdone status <sessionStoryKey> -f json; unrelated dirty stories do not prompt, and the only offered sync command is imdone push <sessionStoryKey>.

An explicit request to use Full or Lightweight HDD, or the trusted imdone-session-story:v1 marker produced by imdone hdd, enables event-triggered progress-note capture for the retained story without a separate consent prompt. An explicit opt-out wins. Story tags and legacy saved metadata alone do not activate capture, and sessions without an explicit request or recognized marker stay off.

Options:

• --light - Start lightweight HDD without the full/light mode prompt
• --resumability-test - Enroll the selected story in the homepage resumability test
• --preserve-global-current - Keep the selected HDD story session-local without changing global current
• -s, --setup - Force issue-key and agent setup before launch

HDD now supports a lighter path for low-risk work, but the lighter path still has a measurement floor. Choose lightweight mode during story triage or Define, capture a minimum success measure before writing the plan, and name the observable outcome, feedback path, and evidence/data-capture mechanism. After the plan is drafted and evaluated, the agent must stop at the plan approval checkpoint before implementation or product-code edits; confirm the evaluated plan to continue, or request plan changes.

After accepting the Hypothesis, choose Continue through the evaluated Plan to batch the remaining Define, Design, and Plan edits locally without routine artifact-review or push prompts. The agent keeps local changes pending until the evaluated Plan checkpoint, where you can keep them local or explicitly push; product-code edits still require Plan approval.

note – Record A Local Issue Progress Note

imdone note PROJ-123 "Changed the implementation path after the failing test exposed a missing fallback"
imdone note PROJ-123 "Override path test" --file /tmp/progress-notes.md
imdone note PROJ-123 "SAFE_EXAMPLE=value" --allow-env SAFE_EXAMPLE
imdone note PROJ-123 "<note>" --event-id <eventId>

Appends a timestamped progress note for an issue. By default, notes are written to the issue’s attachments/progress-notes.md file and the issue body is linked to that attachment when needed.

imdone note blocks obvious credential assignments and environment-variable dumps before writing progress notes. Do not paste environment variables or their values into note text unless the value is safe to persist and the variable name is explicitly allowlisted with --allow-env <name> or comma-separated names.

Each note includes:

• a full ISO timestamp with timezone offset
• the local git author when available
• a fallback author when git identity is unavailable
• the note text

For evidence-bearing notebook entries, prefer this four-line shape:

Observation: <what I saw>
Evidence: <test count / captured response / command output / commit>
Decision: <what we're doing about it, and why over the alternative>
Next: <what the next person should do / trust>

imdone note is local-only. It does not push to Jira or GitHub by itself; run imdone push when you are ready to sync the note attachment and issue-file link to your provider.

Use --event-id <eventId> only for an event-triggered note whose target was already confirmed. The command fails closed when the event is unresolved or its confirmed target differs from issueKey, then records the real attachment path or command failure in the local event ledger. When the opt-in experiment is configured, each transition immediately refreshes a sanitized story summary without pushing it.

Use --file <path> to append the note to a specific file instead of the issue’s default progress-notes attachment.

Use --allow-env <names> only for specific variables that are safe to persist. The command reports when allowlisted environment variable content was recorded without echoing the note value back to the terminal.

pull – Pull Issues from Provider

imdone pull
imdone pull SCRUM-375
imdone pull 123
imdone pull --skip-update

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
• --no-git - Skip git coordination for this pull run while still refreshing provider issues
• --skip-update - Complete provider/Git pull without the automatic post-command update

Fetches issues, comments, and attachments from your configured provider in an isolated synchronization snapshot, then reconciles the durable result into the live Markdown workspace. Clean changes finish automatically; conflicts remain in the live files for editor resolution and imdone merge.

When a pulled issue maps to the done list and an archive folder is configured, imdone writes the issue and its downloaded artifacts to that archive folder. The configured archive directory and everything beneath it stay outside Git operations performed by imdone, regardless of .gitignore rules or existing Git tracking. Git-coordinated pulls still copy archive results from the isolated snapshot into the real archive directory, while direct Git commands and existing tracking remain under your control.

Use imdone pull <issue-key> when you only need to refresh one known issue. Jira-style keys such as SCRUM-375 target Jira, and numeric ids such as 123 target GitHub. This is the shortest single-issue pull form; use --jql or --gql when you need an explicit provider-specific query override.

Use imdone pull --no-git when you only need provider state refreshed and cannot rely on a git repository or git-safe working tree for that operation. This still runs provider configuration checks, provider refresh, project refresh, and empty-directory cleanup, but it skips branch safety, local-change detection, stashing, clean-worktree checks, git commits, stash-pop, and merge-conflict checks. The command output warns that local changes were not protected by git and includes a feedback link for pull-only problems.

Use imdone pull --skip-update in programmatic or concurrent-edit workflows that need the normal provider/Git pull but must not run the automatic follow-up imdone update. The option skips update detection, prompting, and execution only. Omitting it preserves the existing post-command update behavior.

For headless automation such as CI, containers, or Lambda jobs that only read provider issues, install imdone-cli from npm and run imdone pull --no-git. When no anonymous data-capture preference is saved and the process has no TTY, imdone defaults to no anonymous capture instead of prompting. Because --no-git opts out of local-change protection, use it in a disposable workspace or make sure no local issue edits need to be preserved by imdone’s git coordination.

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:

• --jql affects only the Jira provider for that run
• --gql affects only the GitHub provider for that run
• you can use both in the same imdone pull command

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-attachments branch and linked locally
• When an issue is newly pulled and already maps to the done list, it is created directly in the configured archive folder, including when that folder is gitignored

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, --jql affects 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 configured archive folder, including when that folder is gitignored

GitHub query override examples:

# Refresh one GitHub issue by number
imdone pull 123

# 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'

# Refresh provider issue files without git coordination
imdone pull --no-git

Jira issue examples:

# Refresh one Jira issue by key
imdone pull SCRUM-375

push – Push Changes to Provider

imdone push
imdone push PROJ-123
imdone push 17
imdone push --skip-update

Alias: p

Pass an issue key or number to push one issue only. For example, imdone push SCRUM-335 syncs that Jira issue and leaves unrelated local issue changes in your working tree. In mixed Jira/GitHub projects, Jira-style keys such as SCRUM-335 route to Jira, and numeric issue ids such as 17 route to GitHub.

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
• --skip-update - Complete provider/Git push without the automatic post-command update

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.

Use imdone push --skip-update when automation must publish changes without running update detection, prompting, or the follow-up imdone update. Provider/Git synchronization and normal push safeguards still run. Omitting the option preserves the existing post-command update behavior.

Safe synchronization snapshots

Normal Git-coordinated pull, pull <issueKey>, push, push <issueKey>, merge, merge <issueKey>, and mutating add all use the same safety boundary. Imdone captures every pending backlog change at command start—including issue files, comments, attachments, creates, deletes, and renames—and runs provider work in a detached Git worktree. Omitting the key keeps the existing all-provider scope; supplying a key keeps the existing single-issue scope.

Files saved directly by an editor or script after capture cannot enter that provider cycle. During push, the captured starting state is the publication input, so if push’s internal provider refresh overlaps those same paths, imdone restores the captured local versions and continues instead of reporting that expected overlap as a conflict. A targeted imdone push <issueKey> consumes only the selected issue’s captured input; other dirty stories remain byte-for-byte pending in imdone status. Standalone pull preserves files that were already modified when pull began: provider changes integrate, while unchanged local edits remain pending. When both sides append complete progress-note entries, imdone preserves every unique entry once. It also combines an issue heading, body, and metadata changes when the common base proves that each component changed on only one side or changed identically. Competing edits to the same note entry or issue component, malformed story artifacts, and conflicts in other files still fail closed. After the isolated result is durable, imdone reconciles it into the live backlog with Git: non-overlapping post-capture edits remain pending, while genuinely overlapping post-capture changes become normal live conflicts that users resolve in their editor and finish with the matching keyed or backlog-wide merge command. If a provider title change renames a story directory during this flow, imdone follows the stable issue key and restores captured issue, comments, and attachment content into the current directory before publication. Live reconciliation stashes only selected paths that are currently dirty; provider-created paths such as changelog.yml enter through the retained result instead of being treated as live files. If Git creates a reconciliation stash but still reports failure, structured recovery evidence includes that stash ref alongside the operation and result refs.

Targeted commands for different issues can run concurrently, including any combination of imdone push <issueKey> and imdone pull <issueKey>. Provider work overlaps; imdone briefly coordinates only shared Git worktree setup/cleanup and live reconciliation. Each command integrates only its selected story and preserves non-selected dirty files, staged entries, and untracked files. If Git cannot reconcile selected-story content, those live conflicts remain for you to resolve before running imdone merge <issueKey>. This guarantee does not cover concurrent commands for the same issue, unscoped pull/push commands, or --no-git mode.

Structured output always reports:

• whether provider writes occurred;
• all-issues or selected-issue scope, including the selected key;
• live integration status: integrated, conflicts, or recovery-required;
• a content-free operation ID and manifest under the repository Git directory;
• a durable recovery ref such as refs/imdone-sync/operations/<operationId>;
• paths changed after capture and an imdone-native next action.

Normal text output keeps clean completion concise and shows recovery identifiers and support links only when action may be required. Transient conflicts inside the detached worktree are never described as live conflicts. When live integration is clean, synchronization is complete and no follow-up command is required. When reconciliation leaves one selected issue conflicted, resolve its listed files and run:

imdone merge <issueKey>

Use plain imdone merge when you intend to finish every resolved conflict in the backlog. A keyed merge validates one active local issue, publishes and reconciles only that issue, and leaves other dirty files and imdone-materialized unmerged index entries byte-for-byte in place. A selected edit saved after capture remains pending for the next command. This isolation guarantee applies to conflicts created by imdone reconciliation; it does not make an unrelated active Git merge, rebase, or cherry-pick safe to partially complete.

The result ref is recovery evidence, not a required user workflow. Operation manifests contain paths, hashes, and status only—not issue bodies or credentials. A pre-push pull aborts before provider publication when Git reports any unresolved stash-pop path, including structural modify/delete conflicts without marker lines, and materializes those conflicts in the live backlog. Successful imdone merge integrates the resolved staged commits into the live branch so the issue is locally clean when no later edit arrived. If recovery is required, include the structured output’s operation ID when contacting support@imdone.io or reporting a GitHub issue. For add, the manifest records the sanitized provider, key, and URL as soon as remote creation succeeds, preserving recovery evidence if later staged work fails. Existing dirty backlog files and edits made while add runs remain pending, and --body-file content is frozen before the snapshot opens so a later save waits for the next command. imdone pull --no-git remains the documented opt-out for disposable/read-only environments and does not use this Git snapshot protection.

Generated issue-<KEY>.md files must contain one matching provider story. If a clean Git reconciliation produces duplicate story cards or mismatched provider identity, imdone stops, writes a normal LOCAL/PROVIDER conflict in the named file, and retains the operation recovery ref. Resolve that file to one story and run imdone merge <issueKey>, or use plain imdone merge when intentionally completing every resolved conflict. A generated local issue that is already malformed is also rejected before refresh or push can change the provider; if Jira already contains the duplicated description, repair it there first and then retry pull. Provider rejections remain the terminal command error instead of being replaced by a secondary result-processing exception.

The bundled imdone agent skill delegates pull, push, merge, and mutating add to one dedicated agent when the host supports delegation. The primary agent remains available for user-directed work—including direct backlog edits while synchronization runs—so normal agent use continuously exercises the snapshot boundary. Only one synchronization agent runs at a time, read-only commands stay local, and the skill asks before falling back to direct synchronization when delegation is unavailable.

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
• Preserves printable Unicode in Jira descriptions and request bodies while filtering unsafe control characters
• Applies mapped local-list changes as Jira workflow transitions when .imdone/config.yml has a matching statuses[*].list and statuses[*].jira entry

GitHub:

• Uses markdown natively (no conversion needed)
• Applies mapped local-list changes by using native open/closed state mappings or configured GitHub status labels/tags
• Attachments are uploaded to the dedicated imdone-attachments branch; local links are rewritten to the current attachment URL
• imdone push --rewrite-repo-links explicitly 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:true in task metadata to enforce comments on critical issues before pushing.

status – Show Pending Changes

imdone status
imdone status -f json
imdone status PROJ-123 -f json

Alias: st

Shows local file changes across the backlog repo. Backlog issue files are grouped by issue context, and other files in the backlog repo appear under Other changes.

Pass an issue key to return only pending files for that story. HDD uses this form before targeted push reminders so unrelated dirty stories cannot widen the prompt.

Output:

Changes (5 files):

In current-sprint (4 files):
  Added:
    attachment  SCRUM-200    DOING         current-sprint/SCRUM-200-New_plan/attachments/new-plan.md

  Modified:
    task        SCRUM-123    TODO          current-sprint/SCRUM-123-Example/issue-SCRUM-123.md
    comment     SCRUM-123    TODO          current-sprint/SCRUM-123-Example/comments-SCRUM-123.md

  Deleted:
    attachment  SCRUM-456    DONE          current-sprint/SCRUM-456-Screenshot/attachments/screenshot.png

Other changes (1 file):
  Modified:
    README.md

Backlog issue lines show the kind (task, comment, or attachment), the issue key, and the cwd-relative path. Other local changes also show cwd-relative file paths. If the working directory is clean, it prints Working directory is clean.

Use -f, --format for script-readable output:

imdone status --format json
imdone status --format yaml
imdone status --format csv

JSON and YAML output include defaultDirectory, displayDefaultDirectory, statusRootPath, and changes. CSV output emits flattened change rows with path, displayPath, op, kind, issueKey, list, and inDefaultDirectory columns.

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. Mutating creation, pull, metadata, and template work runs in an isolated snapshot, retains durable recovery evidence, and reconciles the created issue into the live backlog. When --labels is omitted, interactive creation lets you search and select zero or more existing imdone tags and applies them as provider labels. The read-only --list-labels, --list-sprints, and --list-issue-types modes do not open a synchronization snapshot.

Options:

• --provider [provider] - Provider to create the issue in (jira or github)
• --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)
• --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
• --list-labels - List existing imdone tags that can be used with --labels, then exit without provider access or issue creation
• --summary [summary] - Issue summary/title
• --labels <labels...> - Existing imdone tags to apply as Jira or GitHub labels; quote tags that contain spaces
• --body <text> - Markdown text to use as the initial issue body
• --body-file <path> - Markdown file to use as the initial issue body
• --no-prompt - Resolve all inputs without prompts and return one input_required result when values are missing or invalid
• -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 or GitHub: Discover valid label values from local imdone tags
imdone add --list-labels

# Coding agent: Read the same deterministic label catalog as JSON
imdone add --list-labels --format json

# 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"

# Jira: Apply existing imdone tags as provider labels
imdone add --provider jira --project-key PROJ --template story --issue-type Story --location backlog --summary "Labeled Jira issue" --labels bug "Needs Review"

# Jira: Create a templated issue with short initial body text
imdone add --project-key PROJ --template story --issue-type Story --location backlog --summary "New feature request" --body "Users need a faster way to create useful issues."

# Jira: Create a templated issue with multiline body markdown
imdone add --project-key PROJ --template story --issue-type Story --location backlog --summary "New feature request" --body-file story-body.md

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

# GitHub: Apply the same existing imdone tags as provider labels
imdone add --provider github --project-key owner/repo --template story --summary "Labeled GitHub issue" --labels bug "Needs Review"

# Coding agent: inspect every unresolved input without prompting or creating
imdone add --no-prompt --summary "Bug fix request" -f json

# Save confirmed reusable Jira defaults, including an explicit no-template choice
imdone agent-config set-add-config --provider jira --project-key PROJ --template none --issue-type Story --location backlog

# Later coding-agent requests reuse those defaults
imdone add --no-prompt --summary "Another request" -f json

# Interactive mode for any provider
imdone add

An input_required result exits non-zero and includes all missing and invalid fields with current choices. It does not switch branches or write to the provider. When the provider is unresolved, the result also includes providerOptions grouped by provider so a coding agent can present every valid path at once:

{
  "status": "input_required",
  "providerOptions": [
    {
      "provider": "jira",
      "fields": [
        { "field": "projectKey", "option": "--project-key", "choices": ["PROJ"] },
        { "field": "issueType", "option": "--issue-type", "choices": ["Story", "Task"] },
        { "field": "location", "option": "--location", "choices": ["backlog", "sprint"] },
        {
          "field": "sprintId",
          "option": "--sprint-id",
          "requiredWhen": { "field": "location", "value": "sprint" },
          "choices": [{ "id": 123, "name": "Sprint 12", "projectKey": "PROJ" }]
        }
      ]
    },
    { "provider": "github", "fields": [] }
  ]
}

Ask one clarification covering the provider and every required choice, then retry once with explicit flags. Use --list-issue-types or --list-sprints only as a fallback when providerOptions is absent. Save only user-confirmed reusable choices with imdone agent-config set-add-config; summaries and body content stay specific to each issue. Successful structured output includes the final applied labels array along with status: created, created: true, the provider issue key, and the cwd-relative local issue path.

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
6. Labels - Select zero or more existing imdone tags to apply as Jira or GitHub labels. Type to search the existing labels, choose a label to add or remove it, then choose Done.

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.

Label discovery: Run imdone add --list-labels to print the canonical existing labels sourced from the local imdone-core project.allTags tag catalog. The command works the same for Jira- and GitHub-backed projects: it does not prompt, contact Jira or GitHub, or create an issue. Use --format json or --format yaml for structured output; it returns an empty list when the project has no existing tags.

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
• Selected imdone tags and template tags converted to provider labels for Jira or GitHub
• A provider-specific replay command showing how to create similar issues without prompts
• Automatic pull of the new issue into your local project
• Cwd-relative issue file output so you can open the new local Markdown file from the same terminal location
• 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):

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
• Provider refresh and push are scoped to the target issue. If the issue was just refreshed in the same command, imdone template skips 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.

Bundled template choices no longer include stock_story, stock_product_mindset_story, or stock_lean_story. The stock full and lightweight HDD templates remain available, and updating imdone does not rewrite stories that were previously created from a retired template.

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

# Finish every resolved imdone conflict
imdone merge

# Finish one Jira issue or numeric GitHub issue
imdone merge <issueKey>

# Emit content-free automation evidence
imdone merge <issueKey> --format json

After resolving conflicts created by imdone reconciliation, run this to push the resolved changes to your configured provider. With an issue key, imdone requires exactly one active local match, captures and publishes only that issue, rejects remaining markers or invalid story structure before provider work, and preserves every unrelated dirty or unmerged path. Omitting the key retains backlog-wide merge behavior. A successful merge leaves the resolved scope clean when no later edit arrived; later saves remain pending or appear as another actionable conflict. Use -f or --format with json, yaml, csv, or text; structured output includes scope, issue key, provider-write state, integration state, operation ID, recovery ref, next action, and support links without issue bodies or credentials.

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.

Before a real status transition, move checks for pending local changes owned by the selected story. If it finds any, it pushes only that story and refreshes the provider state before transitioning; unrelated dirty stories remain pending. A clean selected story skips the push. If the targeted push fails, is aborted, or cannot reconcile safely, the command stops without applying the requested transition. Status discovery and already-at-target commands remain non-mutating.

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

Arguments:

• ISSUE_KEY - The issue identifier (for example, Jira PROJ-123 or 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-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

# 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)

Rebuilds only the configured provider-backed issue directory (for example, current-sprint) from the provider. Uncommitted changes elsewhere in the repository are preserved and do not trigger a prompt.

If the configured issue directory has local changes, imdone reset lists the affected paths and asks once before discarding them. Declining leaves the project unchanged. In a non-interactive terminal, reset fails safely instead of discarding those changes.

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

Validated licenses are stored as IMDONE_LICENSE in ~/.imdone/.env, so one license works across projects. When no home license exists, imdone can still read a legacy project-local IMDONE_LICENSE from the backlog .env; it does not migrate or delete that value during environment loading.

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, cwd-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.

In projects with GitHub issues enabled, the issue argument can be a GitHub issue number such as 121.

Options:

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

Structured output:

• json and yaml include the local issue-context fields for automation, including key, title, status, tags, meta, issueFile, commentsFile, attachmentsDir, and attachments
• csv flattens the same fields for shell and spreadsheet workflows

Notes:

• Paths are relative to the cwd where the command was run, not absolute
• Missing comments or attachments are shown explicitly as none in text output and null / empty arrays in structured output

Examples:

# Interactive mode - search and select issue
imdone show

# Default text format - local shared context
imdone show PROJ-123

# GitHub issue number
imdone show 121

# 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. Issue paths are shown relative to the cwd where the command was run.

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 + cwd-relative 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> - 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 value
• meta.assignedTo="username" - Filter by assignee
• meta.milestone="v1.0" - Filter by milestone (GitHub)
• meta.blocked=* - Show blocked/flagged issues (Jira)
• tag:bug - Filter by tag/label
• meta.isPullRequest=true - Show only pull requests (GitHub)
• meta.status="open" tag:enhancement - Combine multiple filters

workbench – Open The Local Issue Board

imdone workbench
# Short alias:
imdone work

Opens the current project’s configured lists and local issue files as a native, real-time board. The header and its controls remain stationary while the board scrolls independently in either direction, and each column heading stays visible above its vertically scrolling cards. The vertical and horizontal scrollbar tracks sit against the right and bottom window edges while the header and board content retain their inset. Each card shows its unique imdone tags as compact badges beneath the card content. The initial view applies settings.defaultFilter, including its query, sort, and hide: list directives. The workbench reads and writes the same Markdown files as the CLI; it does not contact Jira or GitHub or push provider changes.

The first visible card receives focus when the board opens, so keyboard navigation works immediately. Use the keyboard or pointer to review and organize work:

• Arrow keys move focus between cards and lists
• Shift + Arrow moves or reorders the focused card
• o opens the focused card’s local issue file in VS Code
• Tab and Shift + Tab move through links in the card content and the Send feedback button
• Click selects a card; drag and drop moves it between lists or reorders it within a list
• Double-click opens that card’s local issue file in VS Code
• Reload refreshes the board when an external edit makes a pending move stale
• Right-click workbench content and choose Inspect Element to open the native web inspector on demand; developer tools stay closed during normal startup

Cards show imdone’s truncated formatted content, including safe text formatting and links, instead of title text alone. HTTP and HTTPS links open in the system default browser. The workbench strips active content, event handlers, credentials, and non-web link schemes before content reaches the window, and the renderer cannot choose a native command. Send feedback sits apart from the board and opens an in-workbench form for a bounded message and optional reply email. A successful submission closes the form and leaves a visible confirmation; validation or delivery failures keep the entered values available for correction or retry. Explicit submissions record a dedicated feedback event without sending project names, story content, credentials, tokens, or paths.

External file and configuration edits appear automatically, including project-name changes in the title bar. If a write or browser launch fails, the workbench keeps the last confirmed board and focus visible and announces a recoverable error. Closing the window stops its file watcher and local runtime.

The packaged CLI includes the supported macOS, Linux, and Windows workbench runtimes, so opening the board does not download a browser runtime on first use. Its native icon is generated from the canonical imdone favicon as a transparent 1024×1024 source, preserving the optical margin while giving HiDPI displays enough detail to downsample crisply.

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 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 like PROJ-123 or GitHub issue numbers like 42.

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 pull after each successful git pull to fetch the latest provider issues
• pre-push hook: Runs imdone push before each git push to 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-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