feat: add -f/--force flags, CLI reference for LLMs, update messaging

AmmarSaleh50 · AmmarSaleh50 · commit 44d6adac752c · 2026-04-10T17:25:58.000+02:00
- Add -f/--force flag to delete, delete-scope, and edit commands to skip
  confirmation prompts (useful for scripts and AI agents)
- Remove "Results for:" line from search output for cleaner display
- Add standalone CLI reference markdown (decisionnode-cli.md) for LLMs
- Update "Two interfaces" messaging: CLI is for you and your AI,
  MCP server is for your AI and you
- Add CLI reference links to docs sidebar and footer
diff --git a/README.md b/README.md
@@ -65,7 +65,7 @@ The retrieval is explicit — the AI calls search decisions tool via MCP passing
 
 | | CLI (`decide`) | MCP Server (`decide-mcp`) |
 |---|---|---|
-| **For** | You | Your AI |
+| **For** | You (and your AI) | Your AI (and you) |
 | **How** | Terminal commands | Structured JSON over MCP |
 | **Does** | Setup, add, search, edit, deprecate, export, import, config | Search, add, update, delete, list, history |
 
diff --git a/src/cli.ts b/src/cli.ts
@@ -291,7 +291,7 @@ async function handleSearch() {
             return;
         }
 
-        console.log(`\n  ${c.bold}${c.white}Results for:${c.reset} ${c.dim}"${query}"${c.reset}\n`);
+        console.log('');
 
         for (const result of results) {
             const score = (result.score * 100).toFixed(0);
@@ -513,7 +513,9 @@ async function handleEdit() {
         return;
     }
 
-    if (global) {
+    const force = args.includes('--force') || args.includes('-f');
+
+    if (global && !force) {
         console.log(`\n  ${c.yellow}!${c.reset} This is a global decision that affects ${c.bold}all projects${c.reset}.`);
         const confirm = await prompt(`  Continue editing? ${c.dim}(y/N):${c.reset} `);
         if (confirm.trim().toLowerCase() !== 'y') {
@@ -572,10 +574,14 @@ async function handleDelete() {
         console.log(`  ${c.yellow}!${c.reset} This is a global decision that affects ${c.bold}all projects${c.reset}.`);
     }
 
-    const confirm = await prompt(`  Type ${c.bold}"yes"${c.reset} to confirm: `);
-    if (confirm.trim().toLowerCase() !== 'yes') {
-        console.log(`  ${c.dim}Cancelled.${c.reset}\n`);
-        return;
+    const force = args.includes('--force') || args.includes('-f');
+
+    if (!force) {
+        const confirm = await prompt(`  Type ${c.bold}"yes"${c.reset} to confirm: `);
+        if (confirm.trim().toLowerCase() !== 'yes') {
+            console.log(`  ${c.dim}Cancelled.${c.reset}\n`);
+            return;
+        }
     }
 
     if (global) {
@@ -591,12 +597,14 @@ async function handleDelete() {
             // Ignore clean errors during delete flow
         }
 
-        const renumber = await prompt('Renumber remaining decisions? (y/n): ');
-        if (renumber.trim().toLowerCase() === 'y') {
-            const renames = await renumberDecisions(decision.scope);
-            if (renames.length > 0) {
-                console.log('\nRenumbered:');
-                renames.forEach(r => console.log(`   ${r}`));
+        if (!force) {
+            const renumber = await prompt('Renumber remaining decisions? (y/n): ');
+            if (renumber.trim().toLowerCase() === 'y') {
+                const renames = await renumberDecisions(decision.scope);
+                if (renames.length > 0) {
+                    console.log('\nRenumbered:');
+                    renames.forEach(r => console.log(`   ${r}`));
+                }
             }
         }
     }
@@ -688,15 +696,19 @@ async function handleDeleteScope() {
     }
 
     const decisions = await listDecisions(normalizedInput);
+    const force = args.includes('--force') || args.includes('-f');
+
     console.log(`\n  ${c.red}${c.bold}Delete scope${c.reset} ${c.cyan}${normalizedInput}${c.reset} ${c.dim}(${decisions.length} decisions)${c.reset}\n`);
     decisions.forEach(d => console.log(`    ${c.dim}─${c.reset} ${c.cyan}${d.id}${c.reset}  ${d.decision.substring(0, 50)}`));
 
-    console.log(`\n  ${c.yellow}!${c.reset} This cannot be undone.`);
-    const confirm = await prompt(`  Type the scope name to confirm: `);
+    if (!force) {
+        console.log(`\n  ${c.yellow}!${c.reset} This cannot be undone.`);
+        const confirm = await prompt(`  Type the scope name to confirm: `);
 
-    if (confirm.toLowerCase() !== scopeArg.toLowerCase() && confirm.toLowerCase() !== normalizedInput.toLowerCase()) {
-        console.log(`  ${c.dim}Cancelled.${c.reset}\n`);
-        return;
+        if (confirm.toLowerCase() !== scopeArg.toLowerCase() && confirm.toLowerCase() !== normalizedInput.toLowerCase()) {
+            console.log(`  ${c.dim}Cancelled.${c.reset}\n`);
+            return;
+        }
     }
 
     const result = await deleteScope(scopeArg);
@@ -2038,10 +2050,11 @@ function printUsage() {
     console.log(`    ${c.cyan}list${c.reset}                  ${c.dim}List all decisions (includes global)${c.reset}`);
     console.log(`    ${c.cyan}get${c.reset} ${c.gray}<id>${c.reset}              ${c.dim}View a decision${c.reset}`);
     console.log(`    ${c.cyan}search${c.reset} ${c.gray}"query"${c.reset}        ${c.dim}Semantic search${c.reset}`);
-    console.log(`    ${c.cyan}edit${c.reset} ${c.gray}<id>${c.reset}             ${c.dim}Edit a decision${c.reset}`);
+    console.log(`    ${c.cyan}edit${c.reset} ${c.gray}<id>${c.reset} ${c.gray}[-f]${c.reset}          ${c.dim}Edit a decision (use -f to skip global confirmation)${c.reset}`);
     console.log(`    ${c.cyan}deprecate${c.reset} ${c.gray}<id>${c.reset}        ${c.dim}Hide from search (reversible)${c.reset}`);
     console.log(`    ${c.cyan}activate${c.reset} ${c.gray}<id>${c.reset}         ${c.dim}Re-activate a deprecated decision${c.reset}`);
-    console.log(`    ${c.cyan}delete${c.reset} ${c.gray}<id>${c.reset}           ${c.dim}Permanently delete${c.reset}`);
+    console.log(`    ${c.cyan}delete${c.reset} ${c.gray}<id>${c.reset} ${c.gray}[-f]${c.reset}        ${c.dim}Permanently delete (use -f to skip confirmation)${c.reset}`);
+    console.log(`    ${c.cyan}delete-scope${c.reset} ${c.gray}<scope>${c.reset} ${c.gray}[-f]${c.reset} ${c.dim}Delete entire scope (use -f to skip confirmation)${c.reset}`);
     console.log('');
     console.log(`  ${c.bold}${c.white}Data${c.reset}`);
     console.log(`    ${c.cyan}export${c.reset} ${c.gray}[format]${c.reset}       ${c.dim}Export (md, json, csv)${c.reset}`);
diff --git a/website/public/decisionnode-cli.md b/website/public/decisionnode-cli.md
@@ -0,0 +1,100 @@
+# DecisionNode CLI Reference
+
+> Quick reference for AI agents using the `decide` CLI directly (not via MCP).
+
+---
+
+## When to use the CLI vs MCP
+
+Use the CLI when you need to run shell commands directly (e.g., via a `Bash` tool). Use MCP tools when they're available in your tool list. Both access the same data.
+
+---
+
+## Core Commands
+
+```bash
+# Setup
+decide init                           # Initialize project store
+decide setup                          # Configure Gemini API key
+
+# Add decisions
+decide add                            # Interactive add (prompts for scope, decision, rationale, constraints)
+decide add -s Backend -d "Use PostgreSQL" -r "Team knows SQL" -c "No MongoDB"  # Inline add
+decide add -s Security -d "Never store tokens in localStorage" --global        # Global (all projects)
+decide add -s Backend -d "Use connection pooling" --force                      # Skip conflict check
+
+# Search
+decide search "how should we handle auth?"   # Semantic search (active only, includes global)
+
+# View
+decide list                           # List all decisions (includes global)
+decide list --scope Backend           # Filter by scope
+decide list --global                  # Only global decisions
+decide get backend-001                # View full details
+decide get global:security-001        # View global decision
+
+# Edit
+decide edit backend-001               # Interactive edit
+decide edit global:security-001 -f    # Skip global confirmation
+
+# Lifecycle
+decide deprecate backend-001          # Hide from search, keep embedding (reversible)
+decide activate backend-001           # Re-activate, immediately searchable again
+
+# Delete
+decide delete backend-001 -f          # Permanently delete, skip confirmation
+decide delete-scope Backend -f        # Delete entire scope, skip confirmation
+
+# Data & maintenance
+decide export json                    # Export to terminal (formats: md, json, csv)
+decide export --global                # Export global decisions
+decide import decisions.json          # Import from JSON file
+decide check                          # Show decisions missing embeddings
+decide embed                          # Generate missing embeddings
+decide clean                          # Remove orphaned vectors
+decide history                        # View activity log
+decide history --filter cli           # Filter by source (cli, mcp, cloud)
+decide config                         # View/set configuration
+decide projects                       # List all initialized projects
+```
+
+---
+
+## Decision Structure
+
+```json
+{
+  "id": "backend-001",
+  "scope": "Backend",
+  "decision": "Use PostgreSQL for all persistent storage",
+  "status": "active",
+  "rationale": "Team expertise, ACID compliance, strong ecosystem",
+  "constraints": ["No MongoDB", "No SQLite for production data"],
+  "createdAt": "2024-11-14T09:22:00Z"
+}
+```
+
+**Fields:** `id` (auto-generated), `scope` (required), `decision` (required), `status` (active/deprecated), `rationale` (optional), `constraints` (optional), `createdAt` (auto).
+
+---
+
+## Flags Summary
+
+| Flag | Commands | Effect |
+|------|----------|--------|
+| `-f` / `--force` | `delete`, `delete-scope`, `edit` | Skip confirmation prompts |
+| `--force` | `add` (inline) | Skip conflict check |
+| `--global` | `add`, `list`, `export`, `import` | Use global store (all projects) |
+| `--scope <scope>` | `list` | Filter by scope |
+| `--overwrite` | `import` | Overwrite existing decisions |
+| `--filter <source>` | `history` | Filter by source (`cli`, `mcp`, `cloud`) |
+
+---
+
+## Tips for AI agents
+
+- Always run `decide search` before adding a decision to avoid duplicates.
+- Use `--force` on `add` to skip the conflict check when you're sure it's not a duplicate.
+- Use `-f` on `delete` and `delete-scope` to avoid interactive prompts that will hang.
+- Global decisions (prefixed `global:`) apply to all projects. Use them for cross-cutting concerns like security or coding standards.
+- The CLI logs the source as `cli`. MCP logs the client name (e.g. `claude-code`, `cursor`).
diff --git a/website/public/decisionnode-docs.md b/website/public/decisionnode-docs.md
@@ -14,8 +14,8 @@ The same decision store is accessible from any MCP-compatible tool (Claude Code,
 
 | Interface | For | How |
 |-----------|-----|-----|
-| **CLI** (`decide` / `decisionnode`) | You | Terminal commands, interactive prompts or inline flags |
-| **MCP Server** (`decide-mcp`) | Your AI | Structured JSON over MCP, launched automatically by AI clients |
+| **CLI** (`decide` / `decisionnode`) | You and your AI | Terminal commands, interactive prompts or inline flags |
+| **MCP Server** (`decide-mcp`) | Your AI and you | Structured JSON over MCP, launched automatically by AI clients |
 
 Both read and write to the same local store at `~/.decisionnode/`.
 
@@ -174,7 +174,7 @@ A decision is a scoped JSON object:
 |--------|-----------|-----------|---------------|
 | `active` | Yes | Preserved | Default state |
 | `deprecated` | No | Preserved | `decide deprecate <id>` or `update_decision(status="deprecated")` |
-| (deleted) | N/A | Removed | `decide delete <id>` or `delete_decision(id)` |
+| (deleted) | N/A | Removed | `decide delete <id> [-f]` or `delete_decision(id)` |
 
 Re-activate a deprecated decision: `decide activate <id>` — immediately searchable again.
 
@@ -284,11 +284,11 @@ All commands work with both `decide` and `decisionnode`.
 | `decide list --global` | List only global decisions |
 | `decide get <id>` | View full details (supports `global:` prefix) |
 | `decide search "<query>"` | Semantic search (active only, includes global) |
-| `decide edit <id>` | Edit decision fields (supports `global:` prefix) |
+| `decide edit <id> [-f]` | Edit decision fields (supports `global:` prefix, use `-f` to skip global confirmation) |
 | `decide deprecate <id>` | Hide from search, keep embedding |
 | `decide activate <id>` | Re-activate, immediately searchable |
-| `decide delete <id>` | Permanently delete decision + embedding |
-| `decide delete-scope <scope>` | Delete entire scope |
+| `decide delete <id> [-f]` | Permanently delete decision + embedding (use `-f` to skip confirmation) |
+| `decide delete-scope <scope> [-f]` | Delete entire scope (use `-f` to skip confirmation) |
 
 ### Data & Maintenance
 
diff --git a/website/src/components/Footer.tsx b/website/src/components/Footer.tsx
@@ -59,6 +59,7 @@ export default function Footer() {
                         <ul className="space-y-2">
                             <li><a href="https://github.com/decisionnode/decisionnode" target="_blank" rel="noopener noreferrer" className="text-white/50 hover:text-white transition-colors">GitHub</a></li>
                             <li><a href="/decisionnode-docs.md" target="_blank" rel="noopener" className="text-white/50 hover:text-white transition-colors">Full Docs (Markdown)</a></li>
+                            <li><a href="/decisionnode-cli.md" target="_blank" rel="noopener" className="text-white/50 hover:text-white transition-colors">CLI Reference (Markdown)</a></li>
                             <li><Link to="/docs/workflows" className="text-white/50 hover:text-white transition-colors">Workflows</Link></li>
                         </ul>
                     </div>
diff --git a/website/src/layouts/DocsLayout.tsx b/website/src/layouts/DocsLayout.tsx
@@ -309,6 +309,16 @@ export default function DocsLayout() {
                                         decisionnode-docs.md
                                         <ExternalLink className="w-3 h-3 ml-auto opacity-50" />
                                     </a>
+                                    <a
+                                        href="/decisionnode-cli.md"
+                                        target="_blank"
+                                        rel="noopener"
+                                        className="flex items-center gap-2 px-3 py-2.5 lg:py-2 rounded-md text-sm font-medium transition-colors border-l-2 border-transparent text-zinc-400 hover:text-zinc-200 hover:border-zinc-700"
+                                    >
+                                        <Terminal className="w-4 h-4" />
+                                        decisionnode-cli.md
+                                        <ExternalLink className="w-3 h-3 ml-auto opacity-50" />
+                                    </a>
                                 </div>
                             </div>
                         </nav>
diff --git a/website/src/pages/HomePage.tsx b/website/src/pages/HomePage.tsx
@@ -441,7 +441,7 @@ export default function HomePage() {
                 <section className="max-w-5xl mx-auto px-4 sm:px-6 lg:px-8 py-20 border-b border-white/5 relative z-10">
                     <h2 className="text-2xl font-bold text-white mb-3 text-center">Two interfaces, one store</h2>
                     <p className="text-zinc-500 text-center mb-12 max-w-2xl mx-auto">
-                        The CLI is for you. The MCP server is for your AI. Both read and write to the same local data.
+                        The CLI is for you and your AI. The MCP server is for your AI and you. Both read and write to the same local data.
                     </p>
 
                     <div className="grid md:grid-cols-2 gap-6">
diff --git a/website/src/pages/docs/CliReferencePage.tsx b/website/src/pages/docs/CliReferencePage.tsx
@@ -41,8 +41,8 @@ export default function CliReferencePage() {
             desc: "Semantically search decisions using vector embeddings. Only returns active decisions — deprecated decisions are excluded. Automatically includes global decisions. Requires a Gemini API key."
         },
         {
-            cmd: "decide edit <id>",
-            desc: "Interactively edit a decision's text, rationale, and constraints. Supports global: prefix."
+            cmd: "decide edit <id> [-f]",
+            desc: "Interactively edit a decision's text, rationale, and constraints. Supports global: prefix. Use -f or --force to skip global decision confirmation."
         },
         {
             cmd: "decide deprecate <id>",
@@ -53,12 +53,12 @@ export default function CliReferencePage() {
             desc: "Re-activate a deprecated decision. Immediately searchable again since the embedding is preserved. Supports global: prefix."
         },
         {
-            cmd: "decide delete <id>",
-            desc: "Permanently delete a decision and its embedding. Supports global: prefix. Consider deprecating instead if you might want it back."
+            cmd: "decide delete <id> [-f]",
+            desc: "Permanently delete a decision and its embedding. Supports global: prefix. Use -f or --force to skip confirmation. Consider deprecating instead if you might want it back."
         },
         {
-            cmd: "decide delete-scope <scope>",
-            desc: "Delete an entire scope and all decisions within it."
+            cmd: "decide delete-scope <scope> [-f]",
+            desc: "Delete an entire scope and all decisions within it. Use -f or --force to skip confirmation."
         },
     ];
 
diff --git a/website/src/pages/docs/DocsIntroduction.tsx b/website/src/pages/docs/DocsIntroduction.tsx
@@ -103,11 +103,11 @@ export default function DocsIntroduction() {
                     </p>
                     <div className="grid grid-cols-1 md:grid-cols-2 gap-4 mt-4">
                         <div className="bg-zinc-900/50 p-5 rounded-lg border border-zinc-800">
-                            <p className="text-zinc-200 font-semibold mb-2">CLI — for you</p>
+                            <p className="text-zinc-200 font-semibold mb-2">CLI — for you and your AI</p>
                             <p className="text-sm">The <code>decide</code> command. Use it to set up projects, add decisions, search, export/import, check embedding health, and configure settings. Supports interactive prompts or <Link to="/docs/cli#core-commands" className="text-primary-400 hover:underline">one-command inline flags</Link>.</p>
                         </div>
                         <div className="bg-zinc-900/50 p-5 rounded-lg border border-zinc-800">
-                            <p className="text-zinc-200 font-semibold mb-2">MCP server — for your AI</p>
+                            <p className="text-zinc-200 font-semibold mb-2">MCP server — for your AI and you</p>
                             <p className="text-sm">The <code>decide-mcp</code> binary. Connect it once (e.g. <code>claude mcp add decisionnode -s user decide-mcp</code> for Claude Code) and the AI calls tools like <code>search_decisions</code> and <code>add_decision</code> over <a href="https://modelcontextprotocol.io" className="text-primary-400 hover:underline" target="_blank" rel="noopener noreferrer">MCP</a>. Works with Claude Code, Cursor, Windsurf, Antigravity, or any MCP-compliant tool.</p>
                         </div>
                     </div>
