imdone-cli docs

Install and initialize

Install imdone-cli, run imdone init, and configure provider access.

Get Started

Start with one local setup path, then run imdone init from the project where you want issue context to live.

For macOS arm64, use the standalone DMG when you want to try imdone without installing Node.js or npm first:

# 1) Mount the standalone DMG
hdiutil attach imdone-cli-0.75.0-darwin-arm64.dmg

# 2) Install the native package
sudo installer -pkg /Volumes/imdone-cli-0.75.0-darwin-arm64/imdone-cli-0.75.0-darwin-arm64.pkg -target /

# 3) Run imdone from your terminal
imdone --version
imdone init

The standalone DMG includes a native .pkg installer with the runtime needed to execute imdone. It installs the bundled app under /usr/local/lib/imdone-cli and exposes /usr/local/bin/imdone. The launcher uses system git when git --version succeeds and falls back to the private bundled Git runtime only when system Git is unavailable or unusable. Third-party notices for the bundled Node.js and Git runtimes are installed at /usr/local/lib/imdone-cli/THIRD_PARTY_NOTICES.md. If install or first-run output fails, include the imdone version, platform/architecture, artifact name, installer package name, and command output when contacting support@imdone.io.

Prefer npm or using another platform? Install the published imdone-cli package:

# 1) Install
npm i -g imdone-cli

# 2) Initialize and sync issues
imdone init

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

What you’ll see: A backlog/current-sprint/ directory with one folder per issue. Each issue folder contains the main issue content, comments, lifecycle history in changelog.yml, provider metadata in the issue file, and an attachments/ folder for files and progress notes. Edit Markdown locally; imdone push syncs issue text, comments, notes, labels, status moves, and attachments back to Jira or GitHub using the provider capabilities available for that project.

Try the smallest lab-notebook loop:

imdone pull
imdone show PROJ-123
imdone note PROJ-123 "Observation: The failing checkout test exposes a missing retry path. Evidence: npm test -- --run checkout failed in retry.spec.js. Decision: add the retry branch before touching checkout UI. Next: rerun the focused test, then push the note."
imdone ai PROJ-123 # or: imdone hdd --light PROJ-123
imdone push PROJ-123

That loop keeps the issue useful for the next teammate or AI agent: what changed, what evidence was seen, what decision was made, what blockers remain, and what should happen next.

The same synced issues can also be monitored visually on the imdone kanban board.

Try one resumable story after init

Use the guided start when you want to try HDD Light on one real Jira or GitHub story without copying a story key into a second command:

imdone init --resumability-test

The offer appears only when you pass --resumability-test; ordinary imdone init remains unchanged. Init completes its built-in pull first, then an interactive terminal offers a five-minute test with Yes as the default. Accept to choose an already-pulled story from the guided story picker and start the existing HDD Light resumability-test path. Decline or cancel to finish init normally.

The selected story and experiment record stay local, and nothing is pushed until you run imdone push. In a later session, run ordinary imdone hdd, select the enrolled story from the guided picker, and confirm that you are resuming. Imdone records the resumption and starts the resumed session without an outcome question. On the following launch, it asks one question: whether imdone made the story materially easier to resume. In a non-interactive session, init skips the initial offer and prints imdone hdd --light --resumability-test as the manual enrollment continuation. Existing anonymous-analytics consent controls delivery of fixed decision-stage events; story keys, story contents, repository names, paths, prompts, and email addresses are never included.

Run imdone hdd --light --resumability-test STORY-123 again only when you deliberately want a fresh test for the same story. The explicit enrollment command replaces that story’s prior local attempt, reports its fixed prior status, and starts again without a resumption or outcome question. Ordinary imdone hdd never resets the attempt; it remains the continuation command.

You can try imdone-cli without creating an account. Anonymous CLI users get 50 provider syncs on their device, then 10 provider syncs per month forever on that same device. A provider sync is a command that writes changes back to Jira or GitHub, such as imdone push, imdone add, or imdone move; reading and local discovery commands such as imdone pull, imdone ls, and imdone show do not use that allowance.

When a command that syncs with Jira or GitHub is ready to use anonymous command and error events, imdone-cli asks before capturing them. The answer is saved in your home imdone config and can be yes or no; no issue content, credentials, tokens, email addresses, or file paths are captured in anonymous event payloads.

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

1Password-Managed Credentials

imdone now supports direct 1Password-backed credentials without a wrapper script.

Recommended flow from your software project root:

imdone init --1password
imdone ls
imdone push

Requirements:

  • 1Password CLI: brew install 1password-cli
  • A signed-in 1Password account: op signin

What the direct integration does:

  • Stores Jira and GitHub credentials in 1Password and replaces plain backlog .env secrets with op://... references.
  • Resolves those op://... references automatically when you run imdone directly.
  • Prompts you to migrate when op is available but the repo is still using plain provider secrets in .env.

By default, migration writes items to the Employee vault. Set IMDONE_1PASSWORD_VAULT to target a different vault before running setup:

IMDONE_1PASSWORD_VAULT=Private imdone init --1password