@hasna/knowledge 0.1.0 → 0.2.1

package/bin/open-knowledge.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env bun
+// @bun
+import{mkdirSync as c,readFileSync as L,writeFileSync as u,existsSync as k,renameSync as f,unlinkSync as b}from"fs";import{dirname as m}from"path";import{homedir as i}from"os";import{randomUUID as P}from"crypto";function v(){return`${i()}/.open-knowledge/db.json`}function x(B){if(!k(B))c(m(B),{recursive:!0}),u(B,JSON.stringify({items:[]},null,2))}function d(B){return`${B}.lock`}function g(B,W){let Q=Date.now();while(Date.now()-Q<5000){try{if(!k(B)){u(B,JSON.stringify({owner:W,ts:Date.now()}));return}let C=JSON.parse(L(B,"utf8"));if(Date.now()-C.ts>1e4)b(B)}catch{}let J=Date.now();while(Date.now()-J<50);}throw Error(`Could not acquire lock on ${B} after 5000ms`)}function l(B,W){try{if(k(B)){if(JSON.parse(L(B,"utf8")).owner===W)b(B)}}catch{}}function G(B){x(B);let W=L(B,"utf8"),z=JSON.parse(W);if(!z||!Array.isArray(z.items))return{items:[]};return z}function M(B,W){let z=`${B}.tmp.${P()}`;u(z,JSON.stringify(W,null,2)),f(z,B)}function O(B,W){let z=P(),K=d(B);g(K,z);try{return W()}finally{l(K,z)}}function p(){return`k_${Date.now().toString(36)}_${Math.random().toString(36).slice(2,8)}`}var A={name:"@hasna/knowledge",version:"0.2.1",description:"Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",type:"module",bin:{"open-knowledge":"./src/cli.ts"},scripts:{test:"bun test","test:cli":"bun test tests/cli.test.ts",build:"bun build --target=bun --outfile=bin/open-knowledge.js --minify src/cli.ts",prepublishOnly:"bun run build",postinstall:"bun run build"},keywords:["knowledge","cli","agents","json","notes","local","store"],license:"Apache-2.0",repository:{type:"git",url:"https://github.com/hasna/knowledge"},bugs:{url:"https://github.com/hasna/knowledge/issues"},author:"Hasna Inc. <hasna@example.com>",engines:{bun:">=1.0",node:">=18"}};var h={debug:0,info:1,warn:2,error:3},s=()=>{if(process.env.DEBUG)return"debug";if(process.env.LOG_LEVEL==="debug")return"debug";if(process.env.LOG_LEVEL==="warn")return"warn";if(process.env.LOG_LEVEL==="error")return"error";return"info"};function D(B,W,z){if(h[B]<h[s()])return;let K={debug:"[DEBUG]",info:"[INFO]",warn:"[WARN]",error:"[ERROR]"}[B],Q=z?`${K} ${W} ${JSON.stringify(z)}`:`${K} ${W}`;if(B==="error")console.error(Q);else console.error(Q)}var e=["add","list","get","delete","update","export","prune","dedupe","stats","help"],n={ls:"list",rm:"delete",edit:"update"};function o(B){let W=[],z={};for(let K=0;K<B.length;K+=1){let Q=B[K];if(!Q.startsWith("-")){W.push(Q);continue}switch(Q){case"--json":z.json=!0;break;case"--yes":case"-y":z.yes=!0;break;case"--help":case"-h":z.help=!0;break;case"--version":case"-v":z.version=!0;break;case"--desc":z.desc=!0;break;case"--page":case"-p":z.page=Number(B[K+1]),K+=1;break;case"--limit":case"-l":z.limit=Number(B[K+1]),K+=1;break;case"--search":case"-s":z.search=B[K+1],K+=1;break;case"--sort":z.sort=B[K+1],K+=1;break;case"--id":z.id=B[K+1],K+=1;break;case"--store":z.store=B[K+1],K+=1;break;case"--title":z.title=B[K+1],K+=1;break;case"--content":z.content=B[K+1],K+=1;break;case"--url":z.url=B[K+1],K+=1;break;case"--tag":case"-t":z.tag=B[K+1],K+=1;break;case"--format":z.format=B[K+1],K+=1;break;case"--completions":z.completions=B[K+1],K+=1;break;case"--no-color":z.noColor=!0;break;case"--scope":z.scope=B[K+1],K+=1;break;case"--older-than":z.olderThan=Number(B[K+1]),K+=1;break;case"--empty":z.empty=!0;break;default:throw Error(`Unknown flag: ${Q}. Run 'open-knowledge --help' for valid options.`)}}return{positional:W,flags:z}}function t(B){if(!B)return"";return n[B]??B}function a(B,W){let z=Array.from({length:B.length+1},()=>Array(W.length+1).fill(0));for(let K=0;K<=B.length;K+=1)z[K][0]=K;for(let K=0;K<=W.length;K+=1)z[0][K]=K;for(let K=1;K<=B.length;K+=1)for(let Q=1;Q<=W.length;Q+=1){let J=B[K-1]===W[Q-1]?0:1;z[K][Q]=Math.min(z[K-1][Q]+1,z[K][Q-1]+1,z[K-1][Q-1]+J)}return z[B.length][W.length]}function z0(B){if(!B)return"";let W=[...e,...Object.keys(n)],z="",K=Number.POSITIVE_INFINITY;for(let Q of W){let J=a(B,Q);if(J<K)K=J,z=Q}return K<=3?z:""}function B0(){console.log(`open-knowledge - local agent knowledge store
+
+Usage:
+  open-knowledge <command> [options]
+
+Commands:
+  add <title> <content>       Add an item
+  list (alias: ls)             List items (supports pagination/search/sort/tag)
+  get --id <id>               Get one item
+  update --id <id>            Update an item (--title, --content, --url, --tag)
+  delete (alias: rm) --id <id> Delete item (requires --yes)
+  export                       Export all items (--format jsonl)
+  prune                        Remove old/empty items (requires --yes)
+  dedupe                       Remove duplicate items by title+content (requires --yes)
+  stats                        Show knowledge base statistics
+  help [command]               Show help
+
+Global Options:
+  --json                      Output JSON
+  --store <path>              Override store path
+  --scope local|global|project  Store scope (default: global ~/.open-knowledge/)
+  --no-color                  Disable color output
+  --completions <shell>       Output completions for bash|zsh|fish
+  -v, --version               Show version
+  -h, --help                  Show help
+
+List Options:
+  --format table|json         Output format (default: table if TTY, json otherwise)
+  -p, --page <n>              Page number (default: 1)
+  -l, --limit <n>             Items per page (default: 20)
+  -s, --search <text>         Filter by title/content
+  -t, --tag <tag>             Filter by tag
+  --sort <created|title>       Sort field (default: created)
+  --desc                       Sort descending
+
+Add/Update Options:
+  --url <url>                 Attach source URL
+
+Update Options:
+  --id <id>                   Item id
+  --title <title>             New title
+  --content <content>         New content
+  --url <url>                 New source URL
+  -t, --tag <tag>             Add a tag
+
+Delete Options:
+  --id <id>                   Item id
+  -y, --yes                   Confirm destructive action
+
+Export Options:
+  --format jsonl              Export as newline-delimited JSON (default: JSON array)
+
+Prune Options:
+  --older-than <days>          Remove items older than N days
+  --empty                     Remove items with empty content`)}function K0(B){if(B==="add"){console.log("Usage: open-knowledge add <title> <content> [--url <url>] [-t <tag>] [--json]");return}if(B==="list"||B==="ls"){console.log("Usage: open-knowledge list|ls [--format table|json] [-p <page>] [-l <limit>] [-s <search>] [-t <tag>] [--sort created|title] [--desc] [--json]");return}if(B==="get"){console.log("Usage: open-knowledge get --id <id> [--json]");return}if(B==="update"||B==="edit"){console.log("Usage: open-knowledge update|edit --id <id> [--title <title>] [--content <content>] [--url <url>] [-t <tag>] [--json]");return}if(B==="delete"||B==="rm"){console.log("Usage: open-knowledge delete|rm --id <id> -y [--json]");return}if(B==="export"){console.log("Usage: open-knowledge export [--format jsonl] [--json]");return}if(B==="prune"){console.log("Usage: open-knowledge prune --yes [--older-than <days>] [--empty] [--json]");return}if(B==="dedupe"){console.log("Usage: open-knowledge dedupe --yes [--json]");return}if(B==="stats"){console.log("Usage: open-knowledge stats [--json]");return}B0()}function Q0(B){if(B.noColor||process.env.NO_COLOR)return!1;if(process.env.FORCE_COLOR)return!0;return process.stdout.isTTY===!0}function q(B,W,z){if(W){console.log(JSON.stringify(B,null,2));return}if(typeof B==="string"){console.log(B);return}console.log(B.message??JSON.stringify(B,null,2))}function S(B){if(!B.id)throw Error("Missing required --id. Example: open-knowledge get --id <id>")}function R0(B,W){let z=W.sort??"created";if(z!=="created"&&z!=="title")throw Error("Invalid --sort value. Use 'created' or 'title'.");let K=[...B].sort((Q,J)=>{if(z==="title")return Q.title.localeCompare(J.title);return Q.created_at.localeCompare(J.created_at)});if(W.desc)K.reverse();return{sorted:K,sort:z,direction:W.desc?"desc":"asc"}}function W0(B){let{positional:W,flags:z}=o(B);if(D("debug","CLI invoked",{command:W[0],flags:{json:z.json,store:z.store}}),z.version){console.log(z.json?JSON.stringify({name:A.name,version:A.version},null,2):A.version);return}if(z.completions){let R=z.completions;if(R==="bash")console.log('_open_knowledge() { local cur; cur="${COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update delete export help ls rm edit --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --no-color --scope" -- "$cur")); }; complete -F _open_knowledge open-knowledge');else if(R==="zsh")console.log(`#compdef open-knowledge
+_open_knowledge() { _arguments -C "1: :(add list get update delete export help ls rm edit)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"{created,title}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--no-color)--no-color[disable color]" "(--scope)--scope"{local,global,project}:" }; _open_knowledge`);else if(R==="fish")console.log('complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update delete export help ls rm edit"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"');else throw Error("Invalid --completions value. Use 'bash', 'zsh', or 'fish'.");return}let K=t(W[0]);if(!K||z.help||K==="help"){K0(W[1]);return}let Q=z.store;if(!Q)if(z.scope==="project")Q="./.open-knowledge/db.json";else Q=v();if(x(Q),K==="add"){let R=W[1],Y=W[2];if(!R||!Y)throw Error("Usage: open-knowledge add <title> <content>");O(Q,()=>{let X=G(Q),Z={id:p(),title:R,content:Y,url:z.url??null,tags:z.tag?[z.tag]:[],created_at:new Date().toISOString(),updated_at:new Date().toISOString()};X.items.push(Z),M(Q,X),D("info","Item added",{id:Z.id,title:Z.title}),q({ok:!0,item:Z,message:`Added ${Z.id}`},z.json)});return}if(K==="list"){if(z.format!==void 0&&z.format!=="table"&&z.format!=="json")throw Error("Invalid --format value for list. Use 'table' or 'json'.");O(Q,()=>{let R=G(Q),Y=Number.isFinite(z.page)&&z.page>0?z.page:1,X=Number.isFinite(z.limit)&&z.limit>0?z.limit:20,Z=z.search?String(z.search).toLowerCase():"",N=z.tag?String(z.tag).toLowerCase():"",E=z.format==="table"||!z.json&&!z.format&&Q0(z),U=z.json||z.format==="json",_=R.items;if(Z)_=_.filter(($)=>$.title.toLowerCase().includes(Z)||$.content.toLowerCase().includes(Z));if(N)_=_.filter(($)=>$.tags&&$.tags.map((I)=>I.toLowerCase()).includes(N));let{sorted:H,sort:V,direction:j}=R0(_,z),w=(Y-1)*X,F=H.slice(w,w+X),y=Math.max(1,Math.ceil(H.length/X));if(U){q({ok:!0,page:Y,limit:X,total:H.length,total_pages:y,sort:V,direction:j,items:F},!0);return}if(F.length===0){q(`No items found (search=${Z||"none"}, tag=${N||"none"})`,!1);return}if(E){let $=(T)=>T,I=`${$("ID")}	${$("TITLE")}	${$("CREATED")}	${$("URL")}	${$("TAGS")}`;console.log(I);for(let T of F)console.log(`${T.id}	${$(T.title)}	${T.created_at}	${T.url?$(T.url):""}	${T.tags?.length?$(`[${T.tags.join(", ")}]`):""}`);console.log(`Page ${Y}/${y} | showing ${F.length} of ${H.length} | sort=${V} ${j} | search=${Z||"none"} | tag=${N||"none"}`)}else{for(let $ of F)console.log(`${$.id}	${$.title}	${$.created_at}${$.url?`	${$.url}`:""}${$.tags?.length?`	[${$.tags.join(", ")}]`:""}`);console.log(`Page ${Y}/${y} | showing ${F.length} of ${H.length} | sort=${V} ${j} | search=${Z||"none"} | tag=${N||"none"}`)}});return}if(K==="get"){S(z),O(Q,()=>{let Y=G(Q).items.find((X)=>X.id===z.id);if(!Y)throw Error(`Item not found: ${z.id}`);q({ok:!0,item:Y,message:`${Y.id}: ${Y.title}`},z.json)});return}if(K==="update"){S(z),O(Q,()=>{let R=G(Q),Y=R.items.findIndex((Z)=>Z.id===z.id);if(Y===-1)throw Error(`Item not found: ${z.id}`);let X=R.items[Y];if(z.title!==void 0)X.title=z.title;if(z.content!==void 0)X.content=z.content;if(z.url!==void 0)X.url=z.url;if(z.tag!==void 0){if(X.tags=X.tags||[],!X.tags.map((Z)=>Z.toLowerCase()).includes(z.tag.toLowerCase()))X.tags.push(z.tag)}X.updated_at=new Date().toISOString(),R.items[Y]=X,M(Q,R),q({ok:!0,item:X,message:`Updated ${X.id}`},z.json)});return}if(K==="delete"){if(S(z),!z.yes)throw Error("Refusing delete without --yes. Re-run with: open-knowledge delete --id <id> --yes");O(Q,()=>{let R=G(Q),Y=R.items.length;R.items=R.items.filter((Z)=>Z.id!==z.id);let X=Y!==R.items.length;if(M(Q,R),!X)throw Error(`Item not found: ${z.id}`);D("info","Item deleted",{id:z.id}),q({ok:!0,deleted_id:z.id,message:`Deleted ${z.id}`},z.json)});return}if(K==="export"){let R=z.format??"json";if(R!=="json"&&R!=="jsonl")throw Error("Invalid --format. Use 'json' or 'jsonl'.");O(Q,()=>{let Y=G(Q);if(R==="jsonl")for(let X of Y.items)console.log(JSON.stringify(X));else q({ok:!0,items:Y.items},z.json)});return}if(K==="prune"){if(!z.yes)throw Error("Refusing prune without --yes. Re-run with: open-knowledge prune --yes [--older-than <days>] [--empty]");O(Q,()=>{let R=G(Q),Y=R.items.length;if(z.olderThan!==void 0){let Z=new Date;Z.setDate(Z.getDate()-z.olderThan),R.items=R.items.filter((N)=>new Date(N.created_at)>=Z)}if(z.empty)R.items=R.items.filter((Z)=>Z.content.trim().length>0);let X=Y-R.items.length;M(Q,R),D("info","Prune completed",{pruned:X,remaining:R.items.length}),q({ok:!0,pruned:X,remaining:R.items.length,message:`Pruned ${X} item(s)`},z.json)});return}if(K==="dedupe"){if(!z.yes)throw Error("Refusing dedupe without --yes. Re-run with: open-knowledge dedupe --yes [--json]");O(Q,()=>{let R=G(Q),Y=new Set,X=R.items.length;R.items=R.items.filter((N)=>{let E=`${N.title}\x00${N.content}`;if(Y.has(E))return!1;return Y.add(E),!0});let Z=X-R.items.length;M(Q,R),D("info","Dedupe completed",{removed:Z,remaining:R.items.length}),q({ok:!0,removed:Z,remaining:R.items.length,message:`Dedupe removed ${Z} duplicate(s)`},z.json)});return}if(K==="stats"){O(Q,()=>{let R=G(Q),Y=R.items.length,X=R.items.filter((H)=>H.url).length,Z=R.items.filter((H)=>H.tags&&H.tags.length>0).length,N=Y>0?R.items.map((H)=>H.created_at).sort()[0]:null,E=Y>0?R.items.map((H)=>H.created_at).sort()[Y-1]:null,U={};for(let H of R.items)for(let V of H.tags||[])U[V]=(U[V]||0)+1;let _=Object.entries(U).sort((H,V)=>V[1]-H[1]).slice(0,5).map(([H,V])=>({tag:H,count:V}));q({ok:!0,total:Y,with_url:X,with_tags:Z,oldest:N,newest:E,top_tags:_,message:`${Y} items | ${X} with URL | ${Z} with tags`},z.json)});return}let J=z0(W[0]),C=J?` Did you mean '${J}'?`:"";throw D("warn","Unknown command",{input:W[0],suggestion:J}),Error(`Unknown command: ${W[0]}.${C} Run 'open-knowledge --help' for available commands.`)}if(import.meta.main)try{W0(process.argv.slice(2))}catch(B){let W=B instanceof Error?B.message:String(B);D("error","CLI error",{message:W,stack:B instanceof Error?B.stack:void 0}),console.error(`Error: ${W}`),process.exitCode=1}export{z0 as suggestCommand,R0 as sortItems,W0 as run,o as parseArgs};

package/npmignore

@@ -0,0 +1,9 @@
+tests/
+.github/
+.gitignore
+.git/
+.env*
+*.test.ts
+*.test.js
+tsconfig.json
+bun.lockb

package/package.json

@@ -1,20 +1,38 @@
 {
   "name": "@hasna/knowledge",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   "type": "module",
   "bin": {
-    "open-knowledge": "./src/cli.js"
+    "open-knowledge": "./src/cli.ts"
   },
   "scripts": {
     "test": "bun test",
-    "test:cli": "bun test tests/cli.test.ts"
+    "test:cli": "bun test tests/cli.test.ts",
+    "build": "bun build --target=bun --outfile=bin/open-knowledge.js --minify src/cli.ts",
+    "prepublishOnly": "bun run build",
+    "postinstall": "bun run build"
   },
   "keywords": [
     "knowledge",
     "cli",
     "agents",
-    "json"
+    "json",
+    "notes",
+    "local",
+    "store"
   ],
-  "license": "MIT"
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasna/knowledge"
+  },
+  "bugs": {
+    "url": "https://github.com/hasna/knowledge/issues"
+  },
+  "author": "Hasna Inc. <hasna@example.com>",
+  "engines": {
+    "bun": ">=1.0",
+    "node": ">=18"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,486 @@
+#!/usr/bin/env bun
+/**
+ * @hasna/knowledge
+ * Copyright 2026 Hasna Inc.
+ * Licensed under the Apache License, Version 2.0
+ */
+import { defaultStorePath, loadStore, saveStore, withLock, makeId, ensureStore, type KnowledgeItem } from './store';
+import pkg from '../package.json' with { type: 'json' };
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+const LOG_LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+const currentLevel = (): LogLevel => {
+  if (process.env.DEBUG) return 'debug';
+  if (process.env.LOG_LEVEL === 'debug') return 'debug';
+  if (process.env.LOG_LEVEL === 'warn') return 'warn';
+  if (process.env.LOG_LEVEL === 'error') return 'error';
+  return 'info';
+};
+function log(level: LogLevel, msg: string, data?: Record<string, unknown>): void {
+  if (LOG_LEVELS[level] < LOG_LEVELS[currentLevel()]) return;
+  const prefix = { debug: '[DEBUG]', info: '[INFO]', warn: '[WARN]', error: '[ERROR]' }[level];
+  const entry = data ? `${prefix} ${msg} ${JSON.stringify(data)}` : `${prefix} ${msg}`;
+  if (level === 'error') console.error(entry);
+  else console.error(entry);
+}
+
+interface Flags {
+  json?: boolean;
+  yes?: boolean;
+  help?: boolean;
+  version?: boolean;
+  desc?: boolean;
+  page?: number;
+  limit?: number;
+  search?: string;
+  sort?: string;
+  id?: string;
+  store?: string;
+  title?: string;
+  content?: string;
+  url?: string;
+  tag?: string;
+  format?: string;
+  completions?: string;
+  noColor?: boolean;
+  scope?: string;
+  olderThan?: number;
+  empty?: boolean;
+}
+
+interface ParseResult {
+  positional: string[];
+  flags: Flags;
+}
+
+const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'export', 'prune', 'dedupe', 'stats', 'help'];
+const COMMAND_ALIASES: Record<string, string> = {
+  ls: 'list',
+  rm: 'delete',
+  edit: 'update',
+};
+
+function parseArgs(argv: string[]): ParseResult {
+  const positional: string[] = [];
+  const flags: Flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('-')) {
+      positional.push(token);
+      continue;
+    }
+    switch (token) {
+      case '--json': flags.json = true; break;
+      case '--yes': case '-y': flags.yes = true; break;
+      case '--help': case '-h': flags.help = true; break;
+      case '--version': case '-v': flags.version = true; break;
+      case '--desc': flags.desc = true; break;
+      case '--page': case '-p': flags.page = Number(argv[i + 1]); i += 1; break;
+      case '--limit': case '-l': flags.limit = Number(argv[i + 1]); i += 1; break;
+      case '--search': case '-s': flags.search = argv[i + 1]; i += 1; break;
+      case '--sort': flags.sort = argv[i + 1]; i += 1; break;
+      case '--id': flags.id = argv[i + 1]; i += 1; break;
+      case '--store': flags.store = argv[i + 1]; i += 1; break;
+      case '--title': flags.title = argv[i + 1]; i += 1; break;
+      case '--content': flags.content = argv[i + 1]; i += 1; break;
+      case '--url': flags.url = argv[i + 1]; i += 1; break;
+      case '--tag': case '-t': flags.tag = argv[i + 1]; i += 1; break;
+      case '--format': flags.format = argv[i + 1]; i += 1; break;
+      case '--completions': flags.completions = argv[i + 1]; i += 1; break;
+      case '--no-color': flags.noColor = true; break;
+      case '--scope': flags.scope = argv[i + 1]; i += 1; break;
+      case '--older-than': flags.olderThan = Number(argv[i + 1]); i += 1; break;
+      case '--empty': flags.empty = true; break;
+      default: throw new Error(`Unknown flag: ${token}. Run 'open-knowledge --help' for valid options.`);
+    }
+  }
+  return { positional, flags };
+}
+
+function resolveCommand(raw: string): string {
+  if (!raw) return '';
+  return COMMAND_ALIASES[raw] ?? raw;
+}
+
+function levenshtein(a: string, b: string): number {
+  const dp = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+  for (let i = 0; i <= a.length; i += 1) dp[i][0] = i;
+  for (let j = 0; j <= b.length; j += 1) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i += 1) {
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+    }
+  }
+  return dp[a.length][b.length];
+}
+
+function suggestCommand(input: string): string {
+  if (!input) return '';
+  const all = [...COMMANDS, ...Object.keys(COMMAND_ALIASES)];
+  let best = '';
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const candidate of all) {
+    const score = levenshtein(input, candidate);
+    if (score < bestScore) {
+      bestScore = score;
+      best = candidate;
+    }
+  }
+  return bestScore <= 3 ? best : '';
+}
+
+function printGlobalHelp(): void {
+  console.log(`open-knowledge - local agent knowledge store
+
+Usage:
+  open-knowledge <command> [options]
+
+Commands:
+  add <title> <content>       Add an item
+  list (alias: ls)             List items (supports pagination/search/sort/tag)
+  get --id <id>               Get one item
+  update --id <id>            Update an item (--title, --content, --url, --tag)
+  delete (alias: rm) --id <id> Delete item (requires --yes)
+  export                       Export all items (--format jsonl)
+  prune                        Remove old/empty items (requires --yes)
+  dedupe                       Remove duplicate items by title+content (requires --yes)
+  stats                        Show knowledge base statistics
+  help [command]               Show help
+
+Global Options:
+  --json                      Output JSON
+  --store <path>              Override store path
+  --scope local|global|project  Store scope (default: global ~/.open-knowledge/)
+  --no-color                  Disable color output
+  --completions <shell>       Output completions for bash|zsh|fish
+  -v, --version               Show version
+  -h, --help                  Show help
+
+List Options:
+  --format table|json         Output format (default: table if TTY, json otherwise)
+  -p, --page <n>              Page number (default: 1)
+  -l, --limit <n>             Items per page (default: 20)
+  -s, --search <text>         Filter by title/content
+  -t, --tag <tag>             Filter by tag
+  --sort <created|title>       Sort field (default: created)
+  --desc                       Sort descending
+
+Add/Update Options:
+  --url <url>                 Attach source URL
+
+Update Options:
+  --id <id>                   Item id
+  --title <title>             New title
+  --content <content>         New content
+  --url <url>                 New source URL
+  -t, --tag <tag>             Add a tag
+
+Delete Options:
+  --id <id>                   Item id
+  -y, --yes                   Confirm destructive action
+
+Export Options:
+  --format jsonl              Export as newline-delimited JSON (default: JSON array)
+
+Prune Options:
+  --older-than <days>          Remove items older than N days
+  --empty                     Remove items with empty content`);
+}
+
+function printCommandHelp(command: string): void {
+  if (command === 'add') { console.log('Usage: open-knowledge add <title> <content> [--url <url>] [-t <tag>] [--json]'); return; }
+  if (command === 'list' || command === 'ls') { console.log('Usage: open-knowledge list|ls [--format table|json] [-p <page>] [-l <limit>] [-s <search>] [-t <tag>] [--sort created|title] [--desc] [--json]'); return; }
+  if (command === 'get') { console.log('Usage: open-knowledge get --id <id> [--json]'); return; }
+  if (command === 'update' || command === 'edit') { console.log('Usage: open-knowledge update|edit --id <id> [--title <title>] [--content <content>] [--url <url>] [-t <tag>] [--json]'); return; }
+  if (command === 'delete' || command === 'rm') { console.log('Usage: open-knowledge delete|rm --id <id> -y [--json]'); return; }
+  if (command === 'export') { console.log('Usage: open-knowledge export [--format jsonl] [--json]'); return; }
+  if (command === 'prune') { console.log('Usage: open-knowledge prune --yes [--older-than <days>] [--empty] [--json]'); return; }
+  if (command === 'dedupe') { console.log('Usage: open-knowledge dedupe --yes [--json]'); return; }
+  if (command === 'stats') { console.log('Usage: open-knowledge stats [--json]'); return; }
+  printGlobalHelp();
+}
+
+function useColor(flags: Flags): boolean {
+  if (flags.noColor || process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return process.stdout.isTTY === true;
+}
+
+function output(data: unknown, asJson?: boolean, _flags?: Flags): void {
+  if (asJson) { console.log(JSON.stringify(data, null, 2)); return; }
+  if (typeof data === 'string') { console.log(data); return; }
+  console.log((data as { message?: string }).message ?? JSON.stringify(data, null, 2));
+}
+
+function requireId(flags: Flags): asserts flags is Flags & { id: string } {
+  if (!flags.id) throw new Error('Missing required --id. Example: open-knowledge get --id <id>');
+}
+
+function sortItems(items: KnowledgeItem[], flags: Flags): { sorted: KnowledgeItem[]; sort: string; direction: string } {
+  const sort = flags.sort ?? 'created';
+  if (sort !== 'created' && sort !== 'title') {
+    throw new Error("Invalid --sort value. Use 'created' or 'title'.");
+  }
+  const sorted = [...items].sort((a, b) => {
+    if (sort === 'title') return a.title.localeCompare(b.title);
+    return a.created_at.localeCompare(b.created_at);
+  });
+  if (flags.desc) sorted.reverse();
+  return { sorted, sort, direction: flags.desc ? 'desc' : 'asc' };
+}
+
+function run(argv: string[]): void {
+  const { positional, flags } = parseArgs(argv);
+  log('debug', 'CLI invoked', { command: positional[0], flags: { json: flags.json, store: flags.store } });
+
+  if (flags.version) { console.log(flags.json ? JSON.stringify({ name: pkg.name, version: pkg.version }, null, 2) : pkg.version); return; }
+
+  if (flags.completions) {
+    const shell = flags.completions;
+    if (shell === 'bash') {
+      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update delete export help ls rm edit --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --no-color --scope" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
+    } else if (shell === 'zsh') {
+      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update delete export help ls rm edit)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
+    } else if (shell === 'fish') {
+      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update delete export help ls rm edit"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
+    } else {
+      throw new Error("Invalid --completions value. Use 'bash', 'zsh', or 'fish'.");
+    }
+    return;
+  }
+
+  const command = resolveCommand(positional[0]);
+
+  if (!command || flags.help || command === 'help') { printCommandHelp(positional[1]); return; }
+
+  let storePath = flags.store;
+  if (!storePath) {
+    if (flags.scope === 'project') {
+      storePath = './.open-knowledge/db.json';
+    } else {
+      // local (default) and global both use the global store for now
+      // project scope uses a project-local store
+      storePath = defaultStorePath();
+    }
+  }
+  ensureStore(storePath);
+
+  if (command === 'add') {
+    const title = positional[1];
+    const content = positional[2];
+    if (!title || !content) throw new Error('Usage: open-knowledge add <title> <content>');
+    withLock(storePath, () => {
+      const db = loadStore(storePath);
+      const item: KnowledgeItem = {
+        id: makeId(),
+        title,
+        content,
+        url: flags.url ?? null,
+        tags: flags.tag ? [flags.tag] : [],
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+      };
+      db.items.push(item);
+      saveStore(storePath, db);
+      log('info', 'Item added', { id: item.id, title: item.title });
+      output({ ok: true, item, message: `Added ${item.id}` }, flags.json);
+    });
+    return;
+  }
+
+  if (command === 'list') {
+    if (flags.format !== undefined && flags.format !== 'table' && flags.format !== 'json') {
+      throw new Error("Invalid --format value for list. Use 'table' or 'json'.");
+    }
+    withLock(storePath, () => {
+      const db = loadStore(storePath);
+      const page = Number.isFinite(flags.page) && (flags.page as number) > 0 ? flags.page as number : 1;
+      const limit = Number.isFinite(flags.limit) && (flags.limit as number) > 0 ? flags.limit as number : 20;
+      const search = flags.search ? String(flags.search).toLowerCase() : '';
+      const tag = flags.tag ? String(flags.tag).toLowerCase() : '';
+      const useTable = flags.format === 'table' || (!flags.json && !flags.format && useColor(flags));
+      const useJson = flags.json || flags.format === 'json';
+
+      let filtered = db.items;
+      if (search) filtered = filtered.filter((x) => x.title.toLowerCase().includes(search) || x.content.toLowerCase().includes(search));
+      if (tag) filtered = filtered.filter((x) => x.tags && x.tags.map((t) => t.toLowerCase()).includes(tag));
+
+      const { sorted, sort, direction } = sortItems(filtered, flags);
+      const start = (page - 1) * limit;
+      const rows = sorted.slice(start, start + limit);
+      const totalPages = Math.max(1, Math.ceil(sorted.length / limit));
+
+      if (useJson) { output({ ok: true, page, limit, total: sorted.length, total_pages: totalPages, sort, direction, items: rows }, true); return; }
+      if (rows.length === 0) { output(`No items found (search=${search || 'none'}, tag=${tag || 'none'})`, false); return; }
+      if (useTable) {
+        const col = (v: string) => v;
+        const header = `${col('ID')}\t${col('TITLE')}\t${col('CREATED')}\t${col('URL')}\t${col('TAGS')}`;
+        console.log(header);
+        for (const row of rows) {
+          console.log(`${row.id}\t${col(row.title)}\t${row.created_at}\t${row.url ? col(row.url) : ''}\t${row.tags?.length ? col(`[${row.tags.join(', ')}]`) : ''}`);
+        }
+        console.log(`Page ${page}/${totalPages} | showing ${rows.length} of ${sorted.length} | sort=${sort} ${direction} | search=${search || 'none'} | tag=${tag || 'none'}`);
+      } else {
+        for (const row of rows) {
+          console.log(`${row.id}\t${row.title}\t${row.created_at}${row.url ? `\t${row.url}` : ''}${row.tags?.length ? `\t[${row.tags.join(', ')}]` : ''}`);
+        }
+        console.log(`Page ${page}/${totalPages} | showing ${rows.length} of ${sorted.length} | sort=${sort} ${direction} | search=${search || 'none'} | tag=${tag || 'none'}`);
+      }
+    });
+    return;
+  }
+
+  if (command === 'get') {
+    requireId(flags);
+    withLock(storePath, () => {
+      const db = loadStore(storePath);
+      const item = db.items.find((x) => x.id === flags.id);
+      if (!item) throw new Error(`Item not found: ${flags.id}`);
+      output({ ok: true, item, message: `${item.id}: ${item.title}` }, flags.json);
+    });
+    return;
+  }
+
+  if (command === 'update') {
+    requireId(flags);
+    withLock(storePath, () => {
+      const db = loadStore(storePath);
+      const idx = db.items.findIndex((x) => x.id === flags.id);
+      if (idx === -1) throw new Error(`Item not found: ${flags.id}`);
+      const item = db.items[idx];
+      if (flags.title !== undefined) item.title = flags.title;
+      if (flags.content !== undefined) item.content = flags.content;
+      if (flags.url !== undefined) item.url = flags.url;
+      if (flags.tag !== undefined) {
+        item.tags = item.tags || [];
+        if (!item.tags.map((t) => t.toLowerCase()).includes(flags.tag!.toLowerCase())) {
+          item.tags.push(flags.tag!);
+        }
+      }
+      item.updated_at = new Date().toISOString();
+      db.items[idx] = item;
+      saveStore(storePath, db);
+      output({ ok: true, item, message: `Updated ${item.id}` }, flags.json);
+    });
+    return;
+  }
+
+  if (command === 'delete') {
+    requireId(flags);
+    if (!flags.yes) throw new Error('Refusing delete without --yes. Re-run with: open-knowledge delete --id <id> --yes');
+    withLock(storePath, () => {
+      const db = loadStore(storePath);
+      const before = db.items.length;
+      db.items = db.items.filter((x) => x.id !== flags.id);
+      const deleted = before !== db.items.length;
+      saveStore(storePath, db);
+      if (!deleted) throw new Error(`Item not found: ${flags.id}`);
+      log('info', 'Item deleted', { id: flags.id });
+      output({ ok: true, deleted_id: flags.id, message: `Deleted ${flags.id}` }, flags.json);
+    });
+    return;
+  }
+
+  if (command === 'export') {
+    const format = flags.format ?? 'json';
+    if (format !== 'json' && format !== 'jsonl') throw new Error("Invalid --format. Use 'json' or 'jsonl'.");
+    withLock(storePath, () => {
+      const db = loadStore(storePath);
+      if (format === 'jsonl') {
+        for (const item of db.items) console.log(JSON.stringify(item));
+      } else {
+        output({ ok: true, items: db.items }, flags.json);
+      }
+    });
+    return;
+  }
+
+  if (command === 'prune') {
+    if (!flags.yes) throw new Error('Refusing prune without --yes. Re-run with: open-knowledge prune --yes [--older-than <days>] [--empty]');
+    withLock(storePath, () => {
+      const db = loadStore(storePath);
+      const before = db.items.length;
+      if (flags.olderThan !== undefined) {
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - flags.olderThan);
+        db.items = db.items.filter((x) => new Date(x.created_at) >= cutoff);
+      }
+      if (flags.empty) {
+        db.items = db.items.filter((x) => x.content.trim().length > 0);
+      }
+      const pruned = before - db.items.length;
+      saveStore(storePath, db);
+      log('info', 'Prune completed', { pruned, remaining: db.items.length });
+      output({ ok: true, pruned, remaining: db.items.length, message: `Pruned ${pruned} item(s)` }, flags.json);
+    });
+    return;
+  }
+
+  if (command === 'dedupe') {
+    if (!flags.yes) throw new Error('Refusing dedupe without --yes. Re-run with: open-knowledge dedupe --yes [--json]');
+    withLock(storePath, () => {
+      const db = loadStore(storePath);
+      const seen = new Set<string>();
+      const before = db.items.length;
+      db.items = db.items.filter((x) => {
+        const key = `${x.title}\u0000${x.content}`;
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      });
+      const removed = before - db.items.length;
+      saveStore(storePath, db);
+      log('info', 'Dedupe completed', { removed, remaining: db.items.length });
+      output({ ok: true, removed, remaining: db.items.length, message: `Dedupe removed ${removed} duplicate(s)` }, flags.json);
+    });
+    return;
+  }
+
+  if (command === 'stats') {
+    withLock(storePath, () => {
+      const db = loadStore(storePath);
+      const total = db.items.length;
+      const withUrl = db.items.filter((x) => x.url).length;
+      const withTags = db.items.filter((x) => x.tags && x.tags.length > 0).length;
+      const oldest = total > 0 ? db.items.map((x) => x.created_at).sort()[0] : null;
+      const newest = total > 0 ? db.items.map((x) => x.created_at).sort()[total - 1] : null;
+      const tagCounts: Record<string, number> = {};
+      for (const item of db.items) {
+        for (const tag of item.tags || []) {
+          tagCounts[tag] = (tagCounts[tag] || 0) + 1;
+        }
+      }
+      const topTags = Object.entries(tagCounts).sort((a, b) => b[1] - a[1]).slice(0, 5).map(([tag, count]) => ({ tag, count }));
+      output({
+        ok: true,
+        total,
+        with_url: withUrl,
+        with_tags: withTags,
+        oldest,
+        newest,
+        top_tags: topTags,
+        message: `${total} items | ${withUrl} with URL | ${withTags} with tags`,
+      }, flags.json);
+    });
+    return;
+  }
+
+  const suggestion = suggestCommand(positional[0]);
+  const hint = suggestion ? ` Did you mean '${suggestion}'?` : '';
+  log('warn', 'Unknown command', { input: positional[0], suggestion });
+  throw new Error(`Unknown command: ${positional[0]}.${hint} Run 'open-knowledge --help' for available commands.`);
+}
+
+if (import.meta.main) {
+  try {
+    run(process.argv.slice(2));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    log('error', 'CLI error', { message, stack: error instanceof Error ? error.stack : undefined });
+    console.error(`Error: ${message}`);
+    process.exitCode = 1;
+  }
+}
+
+export { run, parseArgs, suggestCommand, sortItems };