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

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