Commands
ideaBacklog idea management (current worktree; use --main for main worktree)
Backlog idea management for the command line. Targets (which backlog a command operates on): (default) current worktree's backlog -m, --main main worktree's backlog (shared) -s, --system ~/.config/idea/backlog.md (cross-repo; also the default outside a repo) --main and --system are mutually exclusive. --file/-f overrides the backlog path within the selected root (ignored with --system). Shorthand: "idea <text>" is equivalent to "idea add <text>".
idea [text] [flags]idea [command]
| flag | type | description | copy |
|---|---|---|---|
-f, --file | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --main | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --system | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog | ||
-v, --version | version for idea |
No flags match that filter.
show raw -h output
Backlog idea management for the command line. Targets (which backlog a command operates on): (default) current worktree's backlog -m, --main main worktree's backlog (shared) -s, --system ~/.config/idea/backlog.md (cross-repo; also the default outside a repo) --main and --system are mutually exclusive. --file/-f overrides the backlog path within the selected root (ignored with --system). Shorthand: "idea <text>" is equivalent to "idea add <text>". Usage: idea [text] [flags] idea [command] Available Commands: add Add a new idea to the backlog completion Generate the autocompletion script for the specified shell done Mark an idea as done edit Modify an idea's text fmt Rewrite the backlog in canonical form, adopting bare checkboxes help Help about any command list List ideas from the backlog promote Move an idea to the main worktree's backlog prune Bulk-remove all done ideas from the backlog reopen Reopen a completed idea rm Delete an idea from the backlog shell-init Emit shell-eval-safe completion snippet for the given shell show Show a single idea skill Print the agent usage bundle (offline, embedded) update self-update the idea binary via Homebrew Flags: -f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) -h, --help help for idea -m, --main Operate on the main worktree's backlog instead of the current worktree -s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog -v, --version version for idea Use "idea [command] --help" for more information about a command.
idea addAdd a new idea to the backlog
Add a new idea to the current worktree's backlog (fab/backlog.md). The idea is appended as a Markdown checklist line with a generated 4-char ID and today's date. Use --id and --date to override those generated values (handy when importing or backdating). By default the command writes the current worktree's backlog; --main targets the main worktree's backlog, --system targets the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE point at a different file (see "idea --help"). Outside a git repo the system backlog is used automatically. idea add "wire up dark mode" idea add --id a7k2 --date 2026-06-01 "backdated idea"
idea add <text> [flags]
| flag | type | description | copy |
|---|---|---|---|
--date | string | Custom date (YYYY-MM-DD) | |
--id | string | Custom 4-char ID | |
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Add a new idea to the current worktree's backlog (fab/backlog.md).
The idea is appended as a Markdown checklist line with a generated 4-char ID
and today's date. Use --id and --date to override those generated values
(handy when importing or backdating). By default the command writes the
current worktree's backlog; --main targets the main worktree's backlog,
--system targets the system-level backlog (~/.config/idea/backlog.md), and
--file / IDEAS_FILE point at a different file (see "idea --help"). Outside a
git repo the system backlog is used automatically.
idea add "wire up dark mode"
idea add --id a7k2 --date 2026-06-01 "backdated idea"
Usage:
idea add <text> [flags]
Flags:
--date string Custom date (YYYY-MM-DD)
-h, --help help for add
--id string Custom 4-char ID
Global Flags:
-f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo)
-m, --main Operate on the main worktree's backlog instead of the current worktree
-s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea doneMark an idea as done
Mark matching open ideas as done in the current worktree's backlog. Each <query> matches an open idea by its ID or by a case-insensitive substring of its text. If a query matches more than one open idea it is refused and the ambiguous matches are listed, so you can be more specific or use the exact ID. Multiple queries resolve all-or-nothing: every query is resolved before any change is written, so a failing query aborts the batch with the backlog untouched. Two queries resolving to the same idea act on it once (a note on stderr reports the dedupe); confirmations print one per acted idea. --main targets the main worktree's backlog, --system targets the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see "idea --help"). Outside a git repo the system backlog is used automatically. idea done a7k2 idea done "dark mode" idea done a7k2 x9m1 auth-cleanup
idea done <query>... [flags]
| flag | type | description | copy |
|---|---|---|---|
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Mark matching open ideas as done in the current worktree's backlog. Each <query> matches an open idea by its ID or by a case-insensitive substring of its text. If a query matches more than one open idea it is refused and the ambiguous matches are listed, so you can be more specific or use the exact ID. Multiple queries resolve all-or-nothing: every query is resolved before any change is written, so a failing query aborts the batch with the backlog untouched. Two queries resolving to the same idea act on it once (a note on stderr reports the dedupe); confirmations print one per acted idea. --main targets the main worktree's backlog, --system targets the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see "idea --help"). Outside a git repo the system backlog is used automatically. idea done a7k2 idea done "dark mode" idea done a7k2 x9m1 auth-cleanup Usage: idea done <query>... [flags] Flags: -h, --help help for done Global Flags: -f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) -m, --main Operate on the main worktree's backlog instead of the current worktree -s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea editModify an idea's text
Replace a matching idea's text in the current worktree's backlog. With <new-text> the idea's text is replaced inline — the quick one-liner and scripting path. Without it, your editor ($VISUAL, then $EDITOR, then vi) opens on the idea's current text in decoded form (real newlines, real backslashes); saving and exiting cleanly persists the result. An unchanged buffer is a no-op (unless --id/--date is given), an emptied buffer is refused, and a non-zero editor exit aborts without touching the backlog. <query> matches an idea (open or done) by its ID or by a case-insensitive substring of its text. If it matches more than one idea it is refused and the ambiguous matches are listed, so you can be more specific or use the exact ID. --id and --date additionally change the matched idea's ID or date. --main targets the main worktree's backlog, --system targets the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see "idea --help"). Outside a git repo the system backlog is used automatically. idea edit a7k2 "wire up dark mode toggle" idea edit a7k2 # open the current text in your editor idea edit a7k2 --date 2026-06-01 "backdated rewrite"
idea edit <query> [new-text] [flags]
| flag | type | description | copy |
|---|---|---|---|
--date | string | Change the idea's date | |
--id | string | Change the idea's ID | |
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Replace a matching idea's text in the current worktree's backlog.
With <new-text> the idea's text is replaced inline — the quick one-liner and
scripting path. Without it, your editor ($VISUAL, then $EDITOR, then vi)
opens on the idea's current text in decoded form (real newlines, real
backslashes); saving and exiting cleanly persists the result. An unchanged
buffer is a no-op (unless --id/--date is given), an emptied buffer is
refused, and a non-zero editor exit aborts without touching the backlog.
<query> matches an idea (open or done) by its ID or by a case-insensitive
substring of its text. If it matches more than one idea it is refused and the
ambiguous matches are listed, so you can be more specific or use the exact ID.
--id and --date additionally change the matched idea's ID or date. --main
targets the main worktree's backlog, --system targets the system-level backlog
(~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see
"idea --help"). Outside a git repo the system backlog is used automatically.
idea edit a7k2 "wire up dark mode toggle"
idea edit a7k2 # open the current text in your editor
idea edit a7k2 --date 2026-06-01 "backdated rewrite"
Usage:
idea edit <query> [new-text] [flags]
Flags:
--date string Change the idea's date
-h, --help help for edit
--id string Change the idea's ID
Global Flags:
-f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo)
-m, --main Operate on the main worktree's backlog instead of the current worktree
-s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea fmtRewrite the backlog in canonical form, adopting bare checkboxes
Rewrite the current worktree's backlog into canonical form, gofmt-style. Every recognized idea line is regenerated canonically: "-" bullet, no indentation, LF endings, today's date stamped on dateless items, and legacy lone backslashes doubled. Bare checkbox lines without a 4-char [id] anchor (e.g. "- [ ] buy milk", also */+ bullets and [x]/[X]) are adopted as managed ideas: each gets a fresh unique ID and today's date, with its checked state preserved. Lines whose text starts with a bracket (e.g. "- [ ] [DEV-1011] ...") and all other non-idea content keep their text verbatim; line endings canonicalize file-wide (CRLF becomes LF, single trailing LF). A second run is byte-stable, and an already-canonical file is not rewritten at all. stdout stays empty; the report (one "adopted:" line per adopted idea plus summary counts) goes to stderr. --check writes nothing, prints the same report, and exits 1 when the file would change, 0 when it is already canonical. --main targets the main worktree's backlog, --system targets the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see "idea --help"). Outside a git repo the system backlog is used automatically. idea fmt idea fmt --check
idea fmt [flags]
| flag | type | description | copy |
|---|---|---|---|
--check | Write nothing; report what would change and exit 1 if the file is not canonical | ||
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Rewrite the current worktree's backlog into canonical form, gofmt-style.
Every recognized idea line is regenerated canonically: "-" bullet, no
indentation, LF endings, today's date stamped on dateless items, and legacy
lone backslashes doubled. Bare checkbox lines without a 4-char [id] anchor
(e.g. "- [ ] buy milk", also */+ bullets and [x]/[X]) are adopted as managed
ideas: each gets a fresh unique ID and today's date, with its checked state
preserved. Lines whose text starts with a bracket (e.g. "- [ ] [DEV-1011] ...")
and all other non-idea content keep their text verbatim; line endings
canonicalize file-wide (CRLF becomes LF, single trailing LF). A second run is
byte-stable, and an already-canonical file is not rewritten at all.
stdout stays empty; the report (one "adopted:" line per adopted idea plus
summary counts) goes to stderr. --check writes nothing, prints the same report,
and exits 1 when the file would change, 0 when it is already canonical. --main
targets the main worktree's backlog, --system targets the system-level backlog
(~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see
"idea --help"). Outside a git repo the system backlog is used automatically.
idea fmt
idea fmt --check
Usage:
idea fmt [flags]
Flags:
--check Write nothing; report what would change and exit 1 if the file is not canonical
-h, --help help for fmt
Global Flags:
-f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo)
-m, --main Operate on the main worktree's backlog instead of the current worktree
-s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea listList ideas from the backlog
List ideas from the current worktree's backlog (fab/backlog.md). Open ideas are shown by default. Use --all/-a to include done ideas, or --done to show only completed ones. Pass one or more 4-char IDs to list only those ideas. --json emits the structured records (id, date, status, text) for piping into other tools. --sort accepts "date" (default) or "id", and --reverse flips the order. --stale filters to open ideas older than the given number of days ("90d" or "90"); an idea dated exactly that many days ago is not yet stale, and --stale cannot be combined with --done or --all. On a terminal, long idea text is truncated to fit the width (the [id] date: prefix is never clipped) and the prefix is dimmed; --full shows the complete text. Open ideas older than the effective staleness threshold (the --stale value when passed, else 90 days) render entirely faint. When the output is piped or redirected, full canonical lines are emitted regardless of --full so downstream tools see machine-parseable records. As with every backlog command, --main targets the main worktree's backlog, --system targets the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see "idea --help"). Outside a git repo the system backlog is used automatically. idea list idea list --all --sort id idea list --stale 90d idea ls a7k2 b3c9 --full idea list --json
idea list [id...] [flags]
| flag | type | description | copy |
|---|---|---|---|
-a, --all | Show all ideas (open + done) | ||
--done | Show only done ideas | ||
--full | Show full idea text on a terminal (no truncation) | ||
--json | Output as JSON | ||
--reverse | Reverse sort order | ||
--sort | string | Sort by field (id or date) (default "date") | |
--stale | string | Show only open ideas older than N days (e.g. "90d" or "90") | |
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
List ideas from the current worktree's backlog (fab/backlog.md).
Open ideas are shown by default. Use --all/-a to include done ideas, or --done
to show only completed ones. Pass one or more 4-char IDs to list only those
ideas. --json emits the structured records (id, date, status, text) for piping
into other tools. --sort accepts "date" (default) or "id", and --reverse flips
the order.
--stale filters to open ideas older than the given number of days ("90d" or
"90"); an idea dated exactly that many days ago is not yet stale, and --stale
cannot be combined with --done or --all.
On a terminal, long idea text is truncated to fit the width (the [id] date:
prefix is never clipped) and the prefix is dimmed; --full shows the complete
text. Open ideas older than the effective staleness threshold (the --stale
value when passed, else 90 days) render entirely faint. When the output is piped or
redirected, full canonical lines are emitted regardless of --full so downstream
tools see machine-parseable records. As with every backlog command, --main
targets the main worktree's backlog, --system targets the system-level backlog
(~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see "idea
--help"). Outside a git repo the system backlog is used automatically.
idea list
idea list --all --sort id
idea list --stale 90d
idea ls a7k2 b3c9 --full
idea list --json
Usage:
idea list [id...] [flags]
Aliases:
list, ls
Flags:
-a, --all Show all ideas (open + done)
--done Show only done ideas
--full Show full idea text on a terminal (no truncation)
-h, --help help for list
--json Output as JSON
--reverse Reverse sort order
--sort string Sort by field (id or date) (default "date")
--stale string Show only open ideas older than N days (e.g. "90d" or "90")
Global Flags:
-f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo)
-m, --main Operate on the main worktree's backlog instead of the current worktree
-s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea promoteMove an idea to the main worktree's backlog
Move a matching idea from the current worktree's backlog to the main worktree's backlog — the retain step for ideas captured in an ephemeral linked worktree. The idea keeps its ID, date, and open/done status verbatim. The destination is written first and the source second, so a crash mid-move duplicates the idea rather than losing it; both files end in canonical form. If the main backlog already holds an idea with the same ID the move is refused (the ID is never re-minted — external references may key on it) and neither file is touched. Run from the main worktree this is a no-op with a stderr note. --main and --system are rejected: promote defines its own source (current worktree) and destination (main worktree); --file / IDEAS_FILE apply within each root. Outside a git repo there is no main worktree, so promote fails. <query> matches an idea (open or done) by its ID or by a case-insensitive substring of its text. If it matches more than one idea it is refused and the ambiguous matches are listed, so you can be more specific or use the exact ID. idea promote a7k2 idea promote "dark mode"
idea promote <query> [flags]
| flag | type | description | copy |
|---|---|---|---|
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Move a matching idea from the current worktree's backlog to the main worktree's backlog — the retain step for ideas captured in an ephemeral linked worktree. The idea keeps its ID, date, and open/done status verbatim. The destination is written first and the source second, so a crash mid-move duplicates the idea rather than losing it; both files end in canonical form. If the main backlog already holds an idea with the same ID the move is refused (the ID is never re-minted — external references may key on it) and neither file is touched. Run from the main worktree this is a no-op with a stderr note. --main and --system are rejected: promote defines its own source (current worktree) and destination (main worktree); --file / IDEAS_FILE apply within each root. Outside a git repo there is no main worktree, so promote fails. <query> matches an idea (open or done) by its ID or by a case-insensitive substring of its text. If it matches more than one idea it is refused and the ambiguous matches are listed, so you can be more specific or use the exact ID. idea promote a7k2 idea promote "dark mode" Usage: idea promote <query> [flags] Flags: -h, --help help for promote Global Flags: -f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) -m, --main Operate on the main worktree's backlog instead of the current worktree -s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea pruneBulk-remove all done ideas from the backlog
Bulk-remove all done ([x]) ideas from the current worktree's backlog. Without consent this lists each done idea that would be removed. On a terminal it then prompts for confirmation ([y/N]) and deletes only if you confirm; when the output is piped it stays a free dry run (removable lines on stdout, a hint on stderr) and never prompts. --yes/-y (or the equivalent --force) skips the prompt and deletes immediately, printing only a count. There is no archive — the backlog is committed, so git history is the recovery path. Long idea text is truncated to the terminal width (--full shows it in full); piped output is always full and machine-parseable. --main targets the main worktree's backlog, --system targets the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see "idea --help"). Outside a git repo the system backlog is used automatically. idea prune idea prune --yes
idea prune [flags]
| flag | type | description | copy |
|---|---|---|---|
--force | Confirm deletion of all done ideas (alias of --yes) | ||
--full | Show full idea text on a terminal (no truncation) | ||
-y, --yes | Confirm deletion of all done ideas (non-interactive consent) | ||
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Bulk-remove all done ([x]) ideas from the current worktree's backlog.
Without consent this lists each done idea that would be removed. On a terminal
it then prompts for confirmation ([y/N]) and deletes only if you confirm; when
the output is piped it stays a free dry run (removable lines on stdout, a hint
on stderr) and never prompts. --yes/-y (or the equivalent --force) skips the
prompt and deletes immediately, printing only a count. There is no archive —
the backlog is committed, so git history is the recovery path. Long idea text is
truncated to the terminal width (--full shows it in full); piped output is
always full and machine-parseable. --main targets the main worktree's backlog,
--system targets the system-level backlog (~/.config/idea/backlog.md), and
--file / IDEAS_FILE point elsewhere (see "idea --help"). Outside a git repo the
system backlog is used automatically.
idea prune
idea prune --yes
Usage:
idea prune [flags]
Flags:
--force Confirm deletion of all done ideas (alias of --yes)
--full Show full idea text on a terminal (no truncation)
-h, --help help for prune
-y, --yes Confirm deletion of all done ideas (non-interactive consent)
Global Flags:
-f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo)
-m, --main Operate on the main worktree's backlog instead of the current worktree
-s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea reopenReopen a completed idea
Reopen a matching done idea in the current worktree's backlog. <query> matches a done idea by its ID or by a case-insensitive substring of its text. If the query matches more than one done idea it is refused and the ambiguous matches are listed, so you can be more specific or use the exact ID. --main targets the main worktree's backlog, --system targets the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see "idea --help"). Outside a git repo the system backlog is used automatically. idea reopen a7k2 idea reopen "dark mode"
idea reopen <query> [flags]
| flag | type | description | copy |
|---|---|---|---|
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Reopen a matching done idea in the current worktree's backlog. <query> matches a done idea by its ID or by a case-insensitive substring of its text. If the query matches more than one done idea it is refused and the ambiguous matches are listed, so you can be more specific or use the exact ID. --main targets the main worktree's backlog, --system targets the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see "idea --help"). Outside a git repo the system backlog is used automatically. idea reopen a7k2 idea reopen "dark mode" Usage: idea reopen <query> [flags] Flags: -h, --help help for reopen Global Flags: -f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) -m, --main Operate on the main worktree's backlog instead of the current worktree -s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea rmDelete an idea from the backlog
Delete matching ideas from the current worktree's backlog. Each <query> matches an idea (open or done) by its ID or by a case-insensitive substring of its text. If a query matches more than one idea it is refused and the ambiguous matches are listed, so you can be more specific or use the exact ID. Multiple queries resolve all-or-nothing: every query is resolved before any change is written, so a failing query aborts the batch with the backlog untouched. Two queries resolving to the same idea act on it once (a note on stderr reports the dedupe); confirmations print one per removed idea. Confirmation is required to delete: pass --yes/-y (or the equivalent --force); one consent flag covers the whole batch, and without consent the command refuses to remove anything. --dry-run previews every idea that would be deleted (resolved via the same match path) and writes nothing — no consent needed, and it wins over --yes/--force. --main targets the main worktree's backlog, --system targets the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see "idea --help"). Outside a git repo the system backlog is used automatically. idea rm a7k2 --yes idea rm a7k2 x9m1 auth-cleanup --yes idea rm a7k2 x9m1 --dry-run
idea rm <query>... [flags]
| flag | type | description | copy |
|---|---|---|---|
--dry-run | Preview the ideas that would be deleted; write nothing | ||
--force | Confirm deletion (alias of --yes) | ||
-y, --yes | Confirm deletion (non-interactive consent) | ||
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Delete matching ideas from the current worktree's backlog.
Each <query> matches an idea (open or done) by its ID or by a case-insensitive
substring of its text. If a query matches more than one idea it is refused and
the ambiguous matches are listed, so you can be more specific or use the exact
ID. Multiple queries resolve all-or-nothing: every query is resolved before
any change is written, so a failing query aborts the batch with the backlog
untouched. Two queries resolving to the same idea act on it once (a note on
stderr reports the dedupe); confirmations print one per removed idea.
Confirmation is required to delete: pass --yes/-y (or the equivalent --force);
one consent flag covers the whole batch, and without consent the command
refuses to remove anything. --dry-run previews every idea that would be
deleted (resolved via the same match path) and writes nothing — no consent
needed, and it wins over --yes/--force. --main targets the main worktree's
backlog, --system targets the system-level backlog
(~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see
"idea --help"). Outside a git repo the system backlog is used automatically.
idea rm a7k2 --yes
idea rm a7k2 x9m1 auth-cleanup --yes
idea rm a7k2 x9m1 --dry-run
Usage:
idea rm <query>... [flags]
Flags:
--dry-run Preview the ideas that would be deleted; write nothing
--force Confirm deletion (alias of --yes)
-h, --help help for rm
-y, --yes Confirm deletion (non-interactive consent)
Global Flags:
-f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo)
-m, --main Operate on the main worktree's backlog instead of the current worktree
-s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea shell-initEmit shell-eval-safe completion snippet for the given shell
Emit a shell-eval-safe completion snippet for the given shell. Intended to be wired into shell rc files via: echo 'eval "$(idea shell-init zsh)"' >> ~/.zshrc echo 'eval "$(idea shell-init bash)"' >> ~/.bashrc Unlike "idea completion <shell>", the output is wrapped with a banner comment and (for zsh) lazy-loads compinit so the snippet is safe to drop into an rc file even before the user has initialised the completion system. The underlying completion function is generated by cobra and is identical in behavior to "idea completion <shell>". Supported shells: zsh, bash, fish, powershell.
idea shell-init <shell> [flags]
| flag | type | description | copy |
|---|---|---|---|
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Emit a shell-eval-safe completion snippet for the given shell. Intended to be wired into shell rc files via: echo 'eval "$(idea shell-init zsh)"' >> ~/.zshrc echo 'eval "$(idea shell-init bash)"' >> ~/.bashrc Unlike "idea completion <shell>", the output is wrapped with a banner comment and (for zsh) lazy-loads compinit so the snippet is safe to drop into an rc file even before the user has initialised the completion system. The underlying completion function is generated by cobra and is identical in behavior to "idea completion <shell>". Supported shells: zsh, bash, fish, powershell. Usage: idea shell-init <shell> [flags] Flags: -h, --help help for shell-init Global Flags: -f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) -m, --main Operate on the main worktree's backlog instead of the current worktree -s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea showShow a single idea
Show a single matching idea from the current worktree's backlog. <query> matches an idea (open or done) by its ID or by a case-insensitive substring of its text. If it matches more than one idea it is refused and the ambiguous matches are listed, so you can be more specific or use the exact ID. --json emits the structured record (id, date, status, text) instead of the formatted line. --main targets the main worktree's backlog, --system targets the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE point elsewhere (see "idea --help"). Outside a git repo the system backlog is used automatically. idea show a7k2 idea show "dark mode" --json
idea show <query> [flags]
| flag | type | description | copy |
|---|---|---|---|
--json | Output as JSON | ||
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Show a single matching idea from the current worktree's backlog.
<query> matches an idea (open or done) by its ID or by a case-insensitive
substring of its text. If it matches more than one idea it is refused and the
ambiguous matches are listed, so you can be more specific or use the exact ID.
--json emits the structured record (id, date, status, text) instead of the
formatted line. --main targets the main worktree's backlog, --system targets
the system-level backlog (~/.config/idea/backlog.md), and --file / IDEAS_FILE
point elsewhere (see "idea --help"). Outside a git repo the system backlog is
used automatically.
idea show a7k2
idea show "dark mode" --json
Usage:
idea show <query> [flags]
Flags:
-h, --help help for show
--json Output as JSON
Global Flags:
-f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo)
-m, --main Operate on the main worktree's backlog instead of the current worktree
-s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea skillPrint the agent usage bundle (offline, embedded)
Print the agent usage bundle for idea to stdout. A one-page usage briefing for an agent operating an installed idea binary: when to reach for the tool, its capabilities keyed to each subcommand, how it composes with fab-kit, the output/exit-code contracts, and gotchas. It is NOT a flag reference (see "idea <cmd> -h") nor a command tree (see "idea help-dump"). The bundle is raw markdown, printed verbatim with no rendering, no pager, and no added framing — an agent consumes the bytes directly. It is embedded into the binary at build time (byte-identical to the repo's docs/site/skill.md, which also renders at https://shll.ai/idea/skill), so it is offline, static, and versioned with the release. idea skill
idea skill [flags]
| flag | type | description | copy |
|---|---|---|---|
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Print the agent usage bundle for idea to stdout. A one-page usage briefing for an agent operating an installed idea binary: when to reach for the tool, its capabilities keyed to each subcommand, how it composes with fab-kit, the output/exit-code contracts, and gotchas. It is NOT a flag reference (see "idea <cmd> -h") nor a command tree (see "idea help-dump"). The bundle is raw markdown, printed verbatim with no rendering, no pager, and no added framing — an agent consumes the bytes directly. It is embedded into the binary at build time (byte-identical to the repo's docs/site/skill.md, which also renders at https://shll.ai/idea/skill), so it is offline, static, and versioned with the release. idea skill Usage: idea skill [flags] Flags: -h, --help help for skill Global Flags: -f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) -m, --main Operate on the main worktree's backlog instead of the current worktree -s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog
idea updateself-update the idea binary via Homebrew
Self-update the idea binary via Homebrew. Checks the installed idea formula against the latest published release and runs "brew upgrade" only when a newer version exists; if the binary is already current it prints "Already up to date" and exits without upgrading. The tap metadata is refreshed first (via an internal "brew update") so a just-published release is visible. Pass --skip-brew-update to skip only that tap-metadata refresh (faster, but may miss a just-published version) — the version check and any needed upgrade still run. If idea was not installed via Homebrew, the command explains how to update manually instead. idea update idea update --skip-brew-update
idea update [flags]
| flag | type | description | copy |
|---|---|---|---|
--skip-brew-updatebrew update | Skip the internal brew update tap-metadata refresh | ||
-f, --fileglobal | string | Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo) | |
-m, --mainglobal | Operate on the main worktree's backlog instead of the current worktree | ||
-s, --systemglobal | Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog |
No flags match that filter.
show raw -h output
Self-update the idea binary via Homebrew.
Checks the installed idea formula against the latest published release and runs
"brew upgrade" only when a newer version exists; if the binary is already
current it prints "Already up to date" and exits without upgrading. The tap
metadata is refreshed first (via an internal "brew update") so a just-published
release is visible. Pass --skip-brew-update to skip only that tap-metadata
refresh (faster, but may miss a just-published version) — the version check and
any needed upgrade still run. If idea was not installed via Homebrew, the
command explains how to update manually instead.
idea update
idea update --skip-brew-update
Usage:
idea update [flags]
Flags:
-h, --help help for update
--skip-brew-update brew update Skip the internal brew update tap-metadata refresh
Global Flags:
-f, --file string Override backlog file path (relative to the git root, or to ~/.config/idea when outside a repo)
-m, --main Operate on the main worktree's backlog instead of the current worktree
-s, --system Operate on the system-level backlog (~/.config/idea/backlog.md) instead of a repo backlog