@mindtnv/todoist-cli 0.4.0 → 0.5.0

package/src/cli/commands/task/update.ts

@@ -0,0 +1,122 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import { getTask, updateTask } from "../../../api/tasks.ts";
+import type { UpdateTaskParams } from "../../../api/types.ts";
+import { handleError } from "../../../utils/errors.ts";
+import { validateContent, validatePriority, validateDateString } from "../../../utils/validation.ts";
+import { cliExit } from "../../../utils/exit.ts";
+import { resolveTaskArg, resolveProjectArg, resolveSectionArg } from "../../../utils/resolve.ts";
+import { getCliHookRegistry } from "../../plugin-loader.ts";
+
+export function registerUpdateCommand(task: Command): void {
+  task
+    .command("update")
+    .description("Update a task")
+    .argument("<id>", "Task ID")
+    .option("--text <text>", "New content")
+    .option("--priority <priority>", "New priority (1-4)")
+    .option("--due <string>", "New due date string (use 'none' or 'clear' to remove)")
+    .option("--deadline <date>", "Deadline date YYYY-MM-DD (use 'none' or 'clear' to remove)")
+    .option("--description <text>", "New description")
+    .option("--label <spec>", "Add/remove labels. Examples: --label errands (add), --label add:errands, --label remove:waiting. Repeat for multiple.", (val: string, acc: string[]) => { acc.push(val); return acc; }, [] as string[])
+    .option("--project <name-or-id>", "Move to project (name or ID)")
+    .option("--section <name-or-id>", "Move to section (name or ID)")
+    .action(async (rawId: string, opts: { text?: string; priority?: string; due?: string; deadline?: string; description?: string; label: string[]; project?: string; section?: string }) => {
+      try {
+        const id = await resolveTaskArg(rawId);
+
+        // Validate content if provided
+        if (opts.text) {
+          const contentError = validateContent(opts.text);
+          if (contentError) {
+            console.error(chalk.red(contentError));
+            cliExit(1);
+          }
+        }
+
+        // Validate priority if provided
+        if (opts.priority) {
+          const p = parseInt(opts.priority, 10);
+          const priError = validatePriority(p);
+          if (priError) {
+            console.error(chalk.red(priError));
+            cliExit(1);
+          }
+        }
+
+        // Validate deadline format if provided
+        if (opts.deadline && opts.deadline !== "none" && opts.deadline !== "clear") {
+          const dateError = validateDateString(opts.deadline);
+          if (dateError) {
+            console.error(chalk.red(dateError));
+            cliExit(1);
+          }
+        }
+
+        const params: Record<string, unknown> = {};
+        if (opts.text) params.content = opts.text;
+        if (opts.priority) params.priority = parseInt(opts.priority, 10);
+        if (opts.description !== undefined) params.description = opts.description;
+
+        if (opts.due) {
+          if (opts.due === "none" || opts.due === "clear") {
+            params.due_string = null as unknown as string;
+          } else {
+            params.due_string = opts.due;
+          }
+        }
+
+        if (opts.deadline) {
+          if (opts.deadline === "none" || opts.deadline === "clear") {
+            params.deadline_date = null;
+          } else {
+            params.deadline_date = opts.deadline;
+          }
+        }
+
+        if (opts.project) {
+          params.project_id = await resolveProjectArg(opts.project);
+        }
+
+        if (opts.section) {
+          params.section_id = await resolveSectionArg(opts.section, params.project_id as string | undefined);
+        }
+
+        // Handle label add/remove
+        if (opts.label.length > 0) {
+          const task = await getTask(id);
+          let labels = [...task.labels];
+
+          for (const spec of opts.label) {
+            if (spec.startsWith("add:")) {
+              const name = spec.slice(4).replace(/^@/, "");
+              if (!labels.includes(name)) labels.push(name);
+            } else if (spec.startsWith("remove:")) {
+              const name = spec.slice(7).replace(/^@/, "");
+              labels = labels.filter((l) => l !== name);
+            } else {
+              // Treat as add
+              const name = spec.replace(/^@/, "");
+              if (!labels.includes(name)) labels.push(name);
+            }
+          }
+
+          params.labels = labels;
+        }
+
+        if (Object.keys(params).length === 0) {
+          console.error(chalk.red("No update options provided. Use --text, --priority, --due, --deadline, --description, --label, --project, or --section."));
+          cliExit(1);
+        }
+
+        const hooks = getCliHookRegistry();
+        const task = await getTask(id);
+        try { await hooks?.emit("task.updating", { task, changes: params as UpdateTaskParams }); } catch { /* hook errors non-fatal */ }
+        const result = await updateTask(id, params);
+        try { await hooks?.emit("task.updated", { task: result, changes: params as UpdateTaskParams }); } catch { /* hook errors non-fatal */ }
+        console.log(chalk.green(`Task ${result.id} updated: ${result.content}`));
+      } catch (err) {
+        handleError(err);
+      }
+    });
+}

package/src/cli/comment.ts

@@ -0,0 +1,83 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import { getComments, createComment, updateComment, deleteComment } from "../api/comments.ts";
+import { handleError } from "../utils/errors.ts";
+import { ID_WIDTH } from "../utils/format.ts";
+import { resolveTaskArg } from "../utils/resolve.ts";
+
+const POSTED_WIDTH = 22;
+
+export function registerCommentCommand(program: Command): void {
+  const comment = program
+    .command("comment")
+    .description("Manage comments");
+
+  comment
+    .command("add")
+    .description("Add a comment to a task")
+    .argument("<task-id>", "Task ID")
+    .argument("<text>", "Comment text")
+    .action(async (rawTaskId: string, text: string) => {
+      try {
+        const taskId = await resolveTaskArg(rawTaskId);
+        const result = await createComment({ task_id: taskId, content: text });
+        console.log(chalk.green(`Comment added (${result.id})`));
+      } catch (err) {
+        handleError(err);
+      }
+    });
+
+  comment
+    .command("list")
+    .description("List comments for a task")
+    .argument("<task-id>", "Task ID")
+    .action(async (rawTaskId: string) => {
+      try {
+        const taskId = await resolveTaskArg(rawTaskId);
+        const comments = await getComments(taskId);
+        if (comments.length === 0) {
+          console.log(chalk.dim("No comments found."));
+          return;
+        }
+
+        const header = `${"ID".padEnd(ID_WIDTH)} ${"Posted".padEnd(POSTED_WIDTH)} Content`;
+        console.log(chalk.bold(header));
+        console.log(chalk.dim("-".repeat(ID_WIDTH + 1 + POSTED_WIDTH + 1 + 30)));
+
+        for (const c of comments) {
+          const id = c.id.padEnd(ID_WIDTH);
+          const posted = c.posted_at.padEnd(POSTED_WIDTH);
+          console.log(`${id} ${posted} ${c.content}`);
+        }
+      } catch (err) {
+        handleError(err);
+      }
+    });
+
+  comment
+    .command("update")
+    .description("Update a comment")
+    .argument("<id>", "Comment ID")
+    .requiredOption("--text <text>", "New comment text")
+    .action(async (id: string, opts: { text: string }) => {
+      try {
+        const result = await updateComment(id, { content: opts.text });
+        console.log(chalk.green(`Comment ${result.id} updated.`));
+      } catch (err) {
+        handleError(err);
+      }
+    });
+
+  comment
+    .command("delete")
+    .description("Delete a comment")
+    .argument("<id>", "Comment ID")
+    .action(async (id: string) => {
+      try {
+        await deleteComment(id);
+        console.log(chalk.green(`Comment ${id} deleted.`));
+      } catch (err) {
+        handleError(err);
+      }
+    });
+}

package/src/cli/completed.ts

@@ -0,0 +1,87 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import type { CompletedTask } from "../api/types.ts";
+import { getCompletedTasks } from "../api/completed.ts";
+import { getProjects } from "../api/projects.ts";
+import { padEnd } from "../utils/format.ts";
+import { handleError } from "../utils/errors.ts";
+
+function sinceToDate(since: string): string {
+  const now = new Date();
+  switch (since) {
+    case "today": {
+      const d = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+      return d.toISOString();
+    }
+    case "7 days": {
+      const d = new Date(now);
+      d.setDate(d.getDate() - 7);
+      return d.toISOString();
+    }
+    case "30 days": {
+      const d = new Date(now);
+      d.setDate(d.getDate() - 30);
+      return d.toISOString();
+    }
+    default:
+      return since;
+  }
+}
+
+function formatDate(iso: string): string {
+  const d = new Date(iso);
+  return d.toLocaleDateString("en-US", { month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" });
+}
+
+export function registerCompletedCommand(program: Command): void {
+  program
+    .command("completed")
+    .description("Show completed tasks")
+    .option("--since <string>", 'Time range: "today", "7 days", "30 days"', "today")
+    .option("--group-by <field>", "Group by: project")
+    .action(async (opts: { since: string; groupBy?: string }) => {
+      try {
+        const sinceDate = sinceToDate(opts.since);
+        const tasks = await getCompletedTasks(sinceDate);
+
+        if (tasks.length === 0) {
+          console.log(chalk.dim("No completed tasks found."));
+          return;
+        }
+
+        if (opts.groupBy === "project") {
+          const projects = await getProjects();
+          const projectMap = new Map(projects.map((p) => [p.id, p.name]));
+          const groups = new Map<string, CompletedTask[]>();
+
+          for (const t of tasks) {
+            const name = projectMap.get(t.project_id) ?? "Unknown";
+            if (!groups.has(name)) groups.set(name, []);
+            groups.get(name)!.push(t);
+          }
+
+          for (const [projectName, items] of groups) {
+            console.log("");
+            console.log(chalk.bold.underline(projectName) + chalk.dim(` (${items.length})`));
+            for (const t of items) {
+              const date = chalk.dim(formatDate(t.completed_at));
+              console.log(`  ${chalk.green("✓")} ${padEnd(t.content, 45)} ${date}`);
+            }
+          }
+        } else {
+          console.log(chalk.bold(`Completed tasks (since ${opts.since}):`));
+          console.log(chalk.dim("-".repeat(70)));
+
+          for (const t of tasks) {
+            const date = chalk.dim(formatDate(t.completed_at));
+            console.log(`  ${chalk.green("✓")} ${padEnd(t.content, 45)} ${date}`);
+          }
+        }
+
+        console.log("");
+        console.log(chalk.dim(`Total: ${tasks.length} task${tasks.length === 1 ? "" : "s"}`));
+      } catch (err) {
+        handleError(err);
+      }
+    });
+}

package/src/cli/completion.ts

@@ -0,0 +1,360 @@
+import type { Command } from "commander";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import chalk from "chalk";
+import { CONFIG_DIR } from "../config/index.ts";
+import { cliExit } from "../utils/exit.ts";
+
+const COMPLETION_CACHE_PATH = join(CONFIG_DIR, ".completion-cache.json");
+
+export interface CompletionCache {
+  projects: string[];
+  labels: string[];
+  updated_at?: string;
+}
+
+export function getCompletionCache(): CompletionCache {
+  if (!existsSync(COMPLETION_CACHE_PATH)) {
+    return { projects: [], labels: [] };
+  }
+  try {
+    const raw = readFileSync(COMPLETION_CACHE_PATH, "utf-8");
+    return JSON.parse(raw) as CompletionCache;
+  } catch {
+    return { projects: [], labels: [] };
+  }
+}
+
+export function saveCompletionCache(cache: CompletionCache): void {
+  writeFileSync(COMPLETION_CACHE_PATH, JSON.stringify(cache, null, 2), "utf-8");
+}
+
+const BASH_COMPLETION = `#!/usr/bin/env bash
+# todoist CLI bash completion
+_todoist_completions() {
+  local cur prev commands
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  commands="task project label comment template section auth today inbox ui completion completed review matrix log stats next upcoming overdue search deadlines"
+  task_sub="add list complete delete update show reopen move"
+  project_sub="list create delete update show"
+  label_sub="list create delete update"
+  section_sub="list create delete update"
+  comment_sub="add list delete update"
+  template_sub="save apply list"
+
+  # Dynamic completion from cache
+  local cache_file="\${HOME}/.config/todoist-cli/.completion-cache.json"
+  local cached_projects=""
+  local cached_labels=""
+  if [ -f "\${cache_file}" ]; then
+    cached_projects=$(cat "\${cache_file}" | grep -o '"projects":\\s*\\[.*\\]' | sed 's/"projects":\\s*\\[//;s/\\]//;s/"//g;s/,/ /g' 2>/dev/null || echo "")
+    cached_labels=$(cat "\${cache_file}" | grep -o '"labels":\\s*\\[.*\\]' | sed 's/"labels":\\s*\\[//;s/\\]//;s/"//g;s/,/ /g' 2>/dev/null || echo "")
+  fi
+
+  # Complete project names for -P/--project flags
+  case "\${prev}" in
+    -P|--project)
+      COMPREPLY=( $(compgen -W "\${cached_projects}" -- "\${cur}") )
+      return 0
+      ;;
+    -l|--label)
+      COMPREPLY=( $(compgen -W "\${cached_labels}" -- "\${cur}") )
+      return 0
+      ;;
+  esac
+
+  case "\${COMP_WORDS[1]}" in
+    task)
+      COMPREPLY=( $(compgen -W "\${task_sub}" -- "\${cur}") )
+      return 0
+      ;;
+    project)
+      COMPREPLY=( $(compgen -W "\${project_sub}" -- "\${cur}") )
+      return 0
+      ;;
+    label)
+      COMPREPLY=( $(compgen -W "\${label_sub}" -- "\${cur}") )
+      return 0
+      ;;
+    section)
+      COMPREPLY=( $(compgen -W "\${section_sub}" -- "\${cur}") )
+      return 0
+      ;;
+    comment)
+      COMPREPLY=( $(compgen -W "\${comment_sub}" -- "\${cur}") )
+      return 0
+      ;;
+    template)
+      COMPREPLY=( $(compgen -W "\${template_sub}" -- "\${cur}") )
+      return 0
+      ;;
+    completion)
+      COMPREPLY=( $(compgen -W "bash zsh fish update" -- "\${cur}") )
+      return 0
+      ;;
+  esac
+
+  if [ "\${COMP_CWORD}" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "\${commands}" -- "\${cur}") )
+  fi
+  return 0
+}
+complete -F _todoist_completions todoist`;
+
+const ZSH_COMPLETION = `#compdef todoist
+# todoist CLI zsh completion
+
+_todoist_projects() {
+  local cache_file="\${HOME}/.config/todoist-cli/.completion-cache.json"
+  if [[ -f "\${cache_file}" ]]; then
+    local projects
+    projects=(\${(f)"$(cat "\${cache_file}" | python3 -c "import sys,json; [print(p) for p in json.load(sys.stdin).get('projects',[])]" 2>/dev/null)"})
+    compadd -a projects
+  fi
+}
+
+_todoist_labels() {
+  local cache_file="\${HOME}/.config/todoist-cli/.completion-cache.json"
+  if [[ -f "\${cache_file}" ]]; then
+    local labels
+    labels=(\${(f)"$(cat "\${cache_file}" | python3 -c "import sys,json; [print(l) for l in json.load(sys.stdin).get('labels',[])]" 2>/dev/null)"})
+    compadd -a labels
+  fi
+}
+
+_todoist() {
+  local -a commands task_sub project_sub label_sub section_sub comment_sub template_sub
+
+  commands=(
+    'task:Manage tasks'
+    'project:Manage projects'
+    'label:Manage labels'
+    'comment:Manage comments'
+    'template:Manage templates'
+    'section:Manage sections'
+    'auth:Authenticate with Todoist'
+    'today:Show today and overdue tasks'
+    'inbox:Show inbox tasks'
+    'ui:Launch interactive TUI'
+    'completion:Generate shell completion script'
+    'completed:Show completed tasks'
+    'review:Interactive GTD weekly review'
+    'matrix:Eisenhower matrix view'
+    'log:Show activity log'
+    'stats:Show productivity stats'
+    'next:Show highest-priority actionable task'
+    'upcoming:Show tasks for next 7 days'
+    'overdue:Show overdue tasks'
+    'search:Search tasks by text'
+    'deadlines:Show tasks with upcoming deadlines'
+  )
+
+  task_sub=(
+    'add:Add a new task'
+    'list:List tasks'
+    'complete:Complete one or more tasks'
+    'delete:Delete one or more tasks'
+    'update:Update a task'
+    'show:Show full task details'
+    'reopen:Reopen completed tasks'
+    'move:Move task to another project'
+  )
+
+  project_sub=(
+    'list:List all projects'
+    'create:Create a new project'
+    'delete:Delete a project'
+    'update:Update a project'
+    'show:Show project details'
+  )
+
+  label_sub=(
+    'list:List all labels'
+    'create:Create a new label'
+    'delete:Delete a label'
+    'update:Update a label'
+  )
+
+  section_sub=(
+    'list:List sections'
+    'create:Create a new section'
+    'delete:Delete a section'
+    'update:Update a section'
+  )
+
+  comment_sub=(
+    'add:Add a comment to a task'
+    'list:List comments for a task'
+    'delete:Delete a comment'
+    'update:Update a comment'
+  )
+
+  template_sub=(
+    'save:Save a task as a template'
+    'apply:Apply a template'
+    'list:List templates'
+  )
+
+  # Handle -P/--project and -l/--label flag completions
+  case "\${words[CURRENT-1]}" in
+    -P|--project) _todoist_projects; return ;;
+    -l|--label) _todoist_labels; return ;;
+  esac
+
+  if (( CURRENT == 2 )); then
+    _describe -t commands 'todoist commands' commands
+  elif (( CURRENT == 3 )); then
+    case "\${words[2]}" in
+      task) _describe -t task_sub 'task subcommands' task_sub ;;
+      project) _describe -t project_sub 'project subcommands' project_sub ;;
+      label) _describe -t label_sub 'label subcommands' label_sub ;;
+      section) _describe -t section_sub 'section subcommands' section_sub ;;
+      comment) _describe -t comment_sub 'comment subcommands' comment_sub ;;
+      template) _describe -t template_sub 'template subcommands' template_sub ;;
+      completion) _values 'shell or action' bash zsh fish update ;;
+    esac
+  fi
+}
+
+_todoist "$@"`;
+
+const FISH_COMPLETION = `# todoist CLI fish completion
+
+# Disable file completions
+complete -c todoist -f
+
+# Dynamic completion helpers
+function __todoist_cached_projects
+  set -l cache_file "$HOME/.config/todoist-cli/.completion-cache.json"
+  if test -f "$cache_file"
+    cat "$cache_file" | python3 -c "import sys,json; [print(p) for p in json.load(sys.stdin).get('projects',[])]" 2>/dev/null
+  end
+end
+
+function __todoist_cached_labels
+  set -l cache_file "$HOME/.config/todoist-cli/.completion-cache.json"
+  if test -f "$cache_file"
+    cat "$cache_file" | python3 -c "import sys,json; [print(l) for l in json.load(sys.stdin).get('labels',[])]" 2>/dev/null
+  end
+end
+
+# Dynamic completions for -P/--project and -l/--label flags
+complete -c todoist -l project -s P -x -a "(__todoist_cached_projects)" -d "Project name"
+complete -c todoist -l label -s l -x -a "(__todoist_cached_labels)" -d "Label name"
+
+# Main commands
+complete -c todoist -n "__fish_use_subcommand" -a "task" -d "Manage tasks"
+complete -c todoist -n "__fish_use_subcommand" -a "project" -d "Manage projects"
+complete -c todoist -n "__fish_use_subcommand" -a "label" -d "Manage labels"
+complete -c todoist -n "__fish_use_subcommand" -a "comment" -d "Manage comments"
+complete -c todoist -n "__fish_use_subcommand" -a "template" -d "Manage templates"
+complete -c todoist -n "__fish_use_subcommand" -a "section" -d "Manage sections"
+complete -c todoist -n "__fish_use_subcommand" -a "auth" -d "Authenticate with Todoist"
+complete -c todoist -n "__fish_use_subcommand" -a "today" -d "Show today and overdue tasks"
+complete -c todoist -n "__fish_use_subcommand" -a "inbox" -d "Show inbox tasks"
+complete -c todoist -n "__fish_use_subcommand" -a "ui" -d "Launch interactive TUI"
+complete -c todoist -n "__fish_use_subcommand" -a "completion" -d "Generate shell completion script"
+complete -c todoist -n "__fish_use_subcommand" -a "completed" -d "Show completed tasks"
+complete -c todoist -n "__fish_use_subcommand" -a "review" -d "Interactive GTD weekly review"
+complete -c todoist -n "__fish_use_subcommand" -a "matrix" -d "Eisenhower matrix view"
+complete -c todoist -n "__fish_use_subcommand" -a "log" -d "Show activity log"
+complete -c todoist -n "__fish_use_subcommand" -a "stats" -d "Show productivity stats"
+complete -c todoist -n "__fish_use_subcommand" -a "next" -d "Show highest-priority actionable task"
+complete -c todoist -n "__fish_use_subcommand" -a "upcoming" -d "Show tasks for next 7 days"
+complete -c todoist -n "__fish_use_subcommand" -a "overdue" -d "Show overdue tasks"
+complete -c todoist -n "__fish_use_subcommand" -a "search" -d "Search tasks by text"
+complete -c todoist -n "__fish_use_subcommand" -a "deadlines" -d "Show tasks with upcoming deadlines"
+
+# task subcommands
+complete -c todoist -n "__fish_seen_subcommand_from task" -a "add" -d "Add a new task"
+complete -c todoist -n "__fish_seen_subcommand_from task" -a "list" -d "List tasks"
+complete -c todoist -n "__fish_seen_subcommand_from task" -a "complete" -d "Complete one or more tasks"
+complete -c todoist -n "__fish_seen_subcommand_from task" -a "delete" -d "Delete one or more tasks"
+complete -c todoist -n "__fish_seen_subcommand_from task" -a "update" -d "Update a task"
+complete -c todoist -n "__fish_seen_subcommand_from task" -a "show" -d "Show full task details"
+complete -c todoist -n "__fish_seen_subcommand_from task" -a "reopen" -d "Reopen completed tasks"
+complete -c todoist -n "__fish_seen_subcommand_from task" -a "move" -d "Move task to another project"
+
+# project subcommands
+complete -c todoist -n "__fish_seen_subcommand_from project" -a "list" -d "List all projects"
+complete -c todoist -n "__fish_seen_subcommand_from project" -a "create" -d "Create a new project"
+complete -c todoist -n "__fish_seen_subcommand_from project" -a "delete" -d "Delete a project"
+complete -c todoist -n "__fish_seen_subcommand_from project" -a "update" -d "Update a project"
+complete -c todoist -n "__fish_seen_subcommand_from project" -a "show" -d "Show project details"
+
+# label subcommands
+complete -c todoist -n "__fish_seen_subcommand_from label" -a "list" -d "List all labels"
+complete -c todoist -n "__fish_seen_subcommand_from label" -a "create" -d "Create a new label"
+complete -c todoist -n "__fish_seen_subcommand_from label" -a "delete" -d "Delete a label"
+complete -c todoist -n "__fish_seen_subcommand_from label" -a "update" -d "Update a label"
+
+# section subcommands
+complete -c todoist -n "__fish_seen_subcommand_from section" -a "list" -d "List sections"
+complete -c todoist -n "__fish_seen_subcommand_from section" -a "create" -d "Create a new section"
+complete -c todoist -n "__fish_seen_subcommand_from section" -a "delete" -d "Delete a section"
+complete -c todoist -n "__fish_seen_subcommand_from section" -a "update" -d "Update a section"
+
+# comment subcommands
+complete -c todoist -n "__fish_seen_subcommand_from comment" -a "add" -d "Add a comment to a task"
+complete -c todoist -n "__fish_seen_subcommand_from comment" -a "list" -d "List comments for a task"
+complete -c todoist -n "__fish_seen_subcommand_from comment" -a "delete" -d "Delete a comment"
+complete -c todoist -n "__fish_seen_subcommand_from comment" -a "update" -d "Update a comment"
+
+# template subcommands
+complete -c todoist -n "__fish_seen_subcommand_from template" -a "save" -d "Save a task as a template"
+complete -c todoist -n "__fish_seen_subcommand_from template" -a "apply" -d "Apply a template"
+complete -c todoist -n "__fish_seen_subcommand_from template" -a "list" -d "List templates"
+
+# completion subcommands
+complete -c todoist -n "__fish_seen_subcommand_from completion" -a "bash zsh fish update" -d "Shell type or action"`;
+
+async function updateCompletionCache(): Promise<void> {
+  const { getProjects } = await import("../api/projects.ts");
+  const { getLabels } = await import("../api/labels.ts");
+
+  try {
+    const [projects, labels] = await Promise.all([getProjects(), getLabels()]);
+    const cache: CompletionCache = {
+      projects: projects.map((p) => p.name),
+      labels: labels.map((l) => l.name),
+      updated_at: new Date().toISOString(),
+    };
+    saveCompletionCache(cache);
+    console.log(
+      chalk.green(`Completion cache updated: ${cache.projects.length} projects, ${cache.labels.length} labels`)
+    );
+    console.log(chalk.dim(`Saved to ${COMPLETION_CACHE_PATH}`));
+  } catch (err) {
+    console.error(chalk.red(`Failed to update completion cache: ${err instanceof Error ? err.message : err}`));
+    cliExit(1);
+  }
+}
+
+export function registerCompletionCommand(program: Command): void {
+  program
+    .command("completion")
+    .description("Generate shell completion script or update completion cache")
+    .argument("<shell-or-action>", "Shell type (bash, zsh, fish) or 'update' to refresh completion cache")
+    .action(async (arg: string) => {
+      switch (arg) {
+        case "bash":
+          console.log(BASH_COMPLETION);
+          break;
+        case "zsh":
+          console.log(ZSH_COMPLETION);
+          break;
+        case "fish":
+          console.log(FISH_COMPLETION);
+          break;
+        case "update":
+          await updateCompletionCache();
+          break;
+        default:
+          console.error(`Unknown argument: ${arg}. Supported: bash, zsh, fish, update`);
+          cliExit(2);
+      }
+    });
+}