@garyr/pt-cli 1.0.1 → 1.1.0

package/README.md

@@ -42,6 +42,7 @@ graph LR
     - [Quick Start](#quick-start)
         - [Installation](#installation)
         - [Basic Commands](#basic-commands)
+        - [Shell Completions](#shell-completions)
     - [Agent Integration](#agent-integration)
     - [Documentation](#documentation)
     - [Development](#development)
@@ -124,6 +125,25 @@ pt init ./new-project --file my-template.json --yes
 
 ```
 
+### Shell Completions
+
+Generate and install tab completions:
+
+```bash
+# Bash
+pt completion bash > /etc/bash_completion.d/pt
+# Or user-local: pt completion bash > ~/.local/share/bash-completion/completions/pt
+
+# Zsh
+pt completion zsh > ~/.zsh/completions/_pt
+# Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)
+
+# Fish
+pt completion fish > ~/.config/fish/completions/pt.fish
+```
+
+Template names auto-complete dynamically for `pt init`, `pt update`, `pt config`, and `pt remove`.
+
 ## Agent Integration
 
 `pt-cli` is fully compatible with AI agents. By utilizing non-interactive flags (`--yes`, `--vars`, `--name`, `--desc`), agents can autonomously scaffold and learn projects without hanging on interactive terminal prompts.
@@ -191,6 +211,7 @@ pt variables [--set] [--delete] [--json]
 pt default-post-config [--set --json]
 pt ignore [patterns] [--set]
 pt security-response <response>
+pt completion <shell>
 ```
 
 **Config Schema (`~/.pt/config.yaml` v3.0):**

package/dist/commands/completionCommand.js

@@ -0,0 +1,408 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import YAML from 'yaml';
+import { getConfigPath } from '../config.js';
+export function getTemplatesForCompletion() {
+    try {
+        const configPath = getConfigPath();
+        if (!fs.existsSync(configPath)) {
+            return [];
+        }
+        const content = fs.readFileSync(configPath, 'utf-8');
+        if (!content.trim()) {
+            return [];
+        }
+        const parsed = YAML.parse(content);
+        if (!parsed || !parsed.templates || typeof parsed.templates !== 'object') {
+            return [];
+        }
+        return Object.keys(parsed.templates);
+    }
+    catch {
+        return [];
+    }
+}
+export function generateBashCompletion() {
+    return `# Bash completion for pt
+_pt_completions() {
+  local cur prev words cword
+  if declare -F _init_completion >/dev/null 2>&1; then
+    _init_completion || return
+  else
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    words=("\${COMP_WORDS[@]}")
+    cword=$COMP_CWORD
+  fi
+
+  local commands="learn update init config ignore variables default-post-config add remove rm security-response completion"
+
+  # Complete top-level command or global flags
+  if [[ $cword -eq 1 ]]; then
+    if [[ "$cur" == -* ]]; then
+      COMPREPLY=( $(compgen -W "-v --version -h --help" -- "$cur") )
+    else
+      COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+    fi
+    return 0
+  fi
+
+  local cmd="\${words[1]}"
+
+  case "$cmd" in
+    learn)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--ignore -y --yes --name --desc --json --allow-untrusted -h --help" -- "$cur") )
+      fi
+      ;;
+    update)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--ignore -y --yes --desc --no-diff -h --help" -- "$cur") )
+      elif [[ $cword -eq 2 ]]; then
+        local templates
+        templates=$(pt completion --templates 2>/dev/null)
+        COMPREPLY=( $(compgen -W "$templates" -- "$cur") )
+      fi
+      ;;
+    init)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-f --file --skip-post-config --dry-run -y --yes --vars -h --help" -- "$cur") )
+      elif [[ $cword -eq 2 ]]; then
+        local templates
+        templates=$(pt completion --templates 2>/dev/null)
+        COMPREPLY=( $(compgen -W "$templates" -- "$cur") )
+      fi
+      ;;
+    config)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--json -h --help" -- "$cur") )
+      elif [[ $cword -eq 2 ]]; then
+        local templates
+        templates=$(pt completion --templates 2>/dev/null)
+        COMPREPLY=( $(compgen -W "$templates" -- "$cur") )
+      fi
+      ;;
+    ignore)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--set -h --help" -- "$cur") )
+      fi
+      ;;
+    variables)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--set --json --delete -h --help" -- "$cur") )
+      fi
+      ;;
+    default-post-config)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--set --json -h --help" -- "$cur") )
+      fi
+      ;;
+    add)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-f --file -h --help" -- "$cur") )
+      fi
+      ;;
+    remove|rm)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-y --yes -h --help" -- "$cur") )
+      elif [[ $cword -eq 2 ]]; then
+        local templates
+        templates=$(pt completion --templates 2>/dev/null)
+        COMPREPLY=( $(compgen -W "$templates" -- "$cur") )
+      fi
+      ;;
+    completion)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-h --help" -- "$cur") )
+      elif [[ $cword -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
+      fi
+      ;;
+    security-response)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-h --help" -- "$cur") )
+      fi
+      ;;
+  esac
+}
+
+complete -F _pt_completions pt
+`;
+}
+export function generateZshCompletion() {
+    return `#compdef pt
+
+_pt_templates() {
+  local -a templates
+  templates=(\${(f)"$(pt completion --templates 2>/dev/null)"})
+  if [[ \${#templates[@]} -gt 0 ]]; then
+    _describe -t templates 'template' templates
+  fi
+}
+
+_pt() {
+  local context state state_policy
+  typeset -A opt_args
+
+  _arguments -C \\
+    '(-v --version)'{-v,--version}'[output the version number]' \\
+    '(-h --help)'{-h,--help}'[display help for command]' \\
+    '1: :->command' \\
+    '*:: :->args'
+
+  case $state in
+    command)
+      local -a commands
+      commands=(
+        'learn:Learn a project structure from an existing directory'
+        'update:Update an existing template with new structure/files'
+        'init:Initialize a new project from a learned template'
+        'config:Show current config location and list templates, or export a specific template'
+        'ignore:View or set global ignore patterns (comma-separated)'
+        'variables:View or set global variables (comma-separated key=value)'
+        'default-post-config:View or set default post-config tasks'
+        'add:Import/add a template from a JSON string or file'
+        'remove:Remove a learned template from the config'
+        'rm:Remove a learned template from the config'
+        'security-response:Handle security response from GUI'
+        'completion:Generate shell completion script'
+      )
+      _describe -t commands 'pt command' commands
+      ;;
+    args)
+      case $words[1] in
+        learn)
+          _arguments \\
+            '--ignore=[Folder patterns to ignore]:patterns:' \\
+            '(-y --yes)'{-y,--yes}'[Automatically confirm prompts]' \\
+            '--name=[Template name]:name:' \\
+            '--desc=[Template description]:description:' \\
+            '--json[Output template structure as JSON for sharing instead of saving]' \\
+            '--allow-untrusted[Bypass the trusted-source check for remote URLs]' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:path:_files -/'
+          ;;
+        update)
+          _arguments \\
+            '--ignore=[Folder patterns to ignore]:patterns:' \\
+            '(-y --yes)'{-y,--yes}'[Automatically confirm prompts]' \\
+            '--desc=[Template description]:description:' \\
+            '--no-diff[Disable additive mode, show full list]' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:template:_pt_templates' \\
+            '2:sourcePath:_files -/'
+          ;;
+        init)
+          _arguments \\
+            '(-f --file)'{-f,--file}'[Initialize directly from a JSON template file]:file:_files' \\
+            '--skip-post-config[Skip running post-config tasks]' \\
+            '--dry-run[Show what would be created without making changes]' \\
+            '(-y --yes)'{-y,--yes}'[Automatically answer yes to prompts]' \\
+            '--vars=[Comma-separated key=value variables]:variables:' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:template:_pt_templates' \\
+            '2:destPath:_files -/'
+          ;;
+        config)
+          _arguments \\
+            '--json[Output config or specific template as JSON]' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:template:_pt_templates'
+          ;;
+        ignore)
+          _arguments \\
+            '--set[Set the ignore patterns to the provided value]' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:patterns:'
+          ;;
+        variables)
+          _arguments \\
+            '--set[Set the variables to the provided pairs]' \\
+            '--json=[Set variables via JSON string or file]:data:' \\
+            '--delete=[Delete a specific global variable]:key:' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:pairs:'
+          ;;
+        default-post-config)
+          _arguments \\
+            '--set[Set the default post-config tasks via JSON]' \\
+            '--json=[JSON string or file containing tasks array]:data:' \\
+            '(-h --help)'{-h,--help}'[display help for command]'
+          ;;
+        add)
+          _arguments \\
+            '(-f --file)'{-f,--file}'[Path to JSON file containing template data]:file:_files' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:name:' \\
+            '2:json:'
+          ;;
+        remove|rm)
+          _arguments \\
+            '(-y --yes)'{-y,--yes}'[Automatically confirm removal]' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:template:_pt_templates'
+          ;;
+        security-response)
+          _arguments \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:response:'
+          ;;
+        completion)
+          _arguments \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:shell:(bash zsh fish)'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+if [[ "$(basename -- "$0")" != "_pt" ]]; then
+  compdef _pt pt 2>/dev/null || true
+fi
+`;
+}
+export function generateFishCompletion() {
+    return `# Fish completion for pt
+
+function __fish_pt_needs_command
+    set -l cmd (commandline -opc)
+    if [ (count $cmd) -eq 1 ]
+        return 0
+    end
+    return 1
+end
+
+function __fish_pt_using_command
+    set -l cmd (commandline -opc)
+    if [ (count $cmd) -gt 1 ]
+        if [ "$argv[1]" = "$cmd[2]" ]
+            return 0
+        end
+    end
+    return 1
+end
+
+function __fish_pt_templates
+    pt completion --templates 2>/dev/null
+end
+
+# Global options
+complete -c pt -n '__fish_pt_needs_command' -s v -l version -d 'output the version number'
+complete -c pt -n '__fish_pt_needs_command' -s h -l help -d 'display help for command'
+
+# Commands
+complete -c pt -n '__fish_pt_needs_command' -a learn -d 'Learn a project structure from an existing directory'
+complete -c pt -n '__fish_pt_needs_command' -a update -d 'Update an existing template with new structure/files'
+complete -c pt -n '__fish_pt_needs_command' -a init -d 'Initialize a new project from a learned template'
+complete -c pt -n '__fish_pt_needs_command' -a config -d 'Show current config location and list templates, or export a specific template'
+complete -c pt -n '__fish_pt_needs_command' -a ignore -d 'View or set global ignore patterns (comma-separated)'
+complete -c pt -n '__fish_pt_needs_command' -a variables -d 'View or set global variables (comma-separated key=value)'
+complete -c pt -n '__fish_pt_needs_command' -a default-post-config -d 'View or set default post-config tasks'
+complete -c pt -n '__fish_pt_needs_command' -a add -d 'Import/add a template from a JSON string or file'
+complete -c pt -n '__fish_pt_needs_command' -a remove -d 'Remove a learned template from the config'
+complete -c pt -n '__fish_pt_needs_command' -a rm -d 'Remove a learned template from the config'
+complete -c pt -n '__fish_pt_needs_command' -a security-response -d 'Handle security response from GUI'
+complete -c pt -n '__fish_pt_needs_command' -a completion -d 'Generate shell completion script'
+
+# learn
+complete -c pt -n '__fish_pt_using_command learn' -l ignore -d 'Folder patterns to ignore (comma-separated)'
+complete -c pt -n '__fish_pt_using_command learn' -s y -l yes -d 'Automatically confirm prompts'
+complete -c pt -n '__fish_pt_using_command learn' -l name -d 'Template name (skip prompt)'
+complete -c pt -n '__fish_pt_using_command learn' -l desc -d 'Template description (skip prompt)'
+complete -c pt -n '__fish_pt_using_command learn' -l json -d 'Output template structure as JSON for sharing instead of saving'
+complete -c pt -n '__fish_pt_using_command learn' -l allow-untrusted -d 'Bypass the trusted-source check for remote URLs'
+
+# update
+complete -c pt -n '__fish_pt_using_command update' -a '(__fish_pt_templates)' -d 'Template name'
+complete -c pt -n '__fish_pt_using_command update' -l ignore -d 'Folder patterns to ignore (comma-separated)'
+complete -c pt -n '__fish_pt_using_command update' -s y -l yes -d 'Automatically confirm prompts'
+complete -c pt -n '__fish_pt_using_command update' -l desc -d 'Template description (skip prompt)'
+complete -c pt -n '__fish_pt_using_command update' -l no-diff -d 'Disable additive mode, show full list'
+
+# init
+complete -c pt -n '__fish_pt_using_command init' -a '(__fish_pt_templates)' -d 'Template name'
+complete -c pt -n '__fish_pt_using_command init' -s f -l file -d 'Initialize directly from a JSON template file without adding it to local config'
+complete -c pt -n '__fish_pt_using_command init' -l skip-post-config -d 'Skip running post-config tasks'
+complete -c pt -n '__fish_pt_using_command init' -l dry-run -d 'Show what would be created without making changes'
+complete -c pt -n '__fish_pt_using_command init' -s y -l yes -d 'Automatically answer yes to prompts'
+complete -c pt -n '__fish_pt_using_command init' -l vars -d 'Comma-separated key=value variables'
+
+# config
+complete -c pt -n '__fish_pt_using_command config' -a '(__fish_pt_templates)' -d 'Template name'
+complete -c pt -n '__fish_pt_using_command config' -l json -d 'Output config or specific template as JSON'
+
+# ignore
+complete -c pt -n '__fish_pt_using_command ignore' -l set -d 'Set the ignore patterns to the provided value'
+
+# variables
+complete -c pt -n '__fish_pt_using_command variables' -l set -d 'Set the variables to the provided pairs'
+complete -c pt -n '__fish_pt_using_command variables' -l json -d 'Set variables via JSON string or file'
+complete -c pt -n '__fish_pt_using_command variables' -l delete -d 'Delete a specific global variable'
+
+# default-post-config
+complete -c pt -n '__fish_pt_using_command default-post-config' -l set -d 'Set the default post-config tasks via JSON'
+complete -c pt -n '__fish_pt_using_command default-post-config' -l json -d 'JSON string or file containing tasks array'
+
+# add
+complete -c pt -n '__fish_pt_using_command add' -s f -l file -d 'Path to JSON file containing template data'
+
+# remove / rm
+complete -c pt -n '__fish_pt_using_command remove' -a '(__fish_pt_templates)' -d 'Template name'
+complete -c pt -n '__fish_pt_using_command remove' -s y -l yes -d 'Automatically confirm removal'
+complete -c pt -n '__fish_pt_using_command rm' -a '(__fish_pt_templates)' -d 'Template name'
+complete -c pt -n '__fish_pt_using_command rm' -s y -l yes -d 'Automatically confirm removal'
+
+# completion
+complete -c pt -n '__fish_pt_using_command completion' -a 'bash zsh fish' -d 'Shell'
+`;
+}
+export function generateShellScript(shell) {
+    switch (shell.toLowerCase()) {
+        case 'bash':
+            return generateBashCompletion();
+        case 'zsh':
+            return generateZshCompletion();
+        case 'fish':
+            return generateFishCompletion();
+        default: {
+            const supported = ['bash', 'zsh', 'fish'];
+            throw new Error(`Unsupported shell: ${shell}. Supported: ${supported.join(', ')}`);
+        }
+    }
+}
+export function generateCompletion(shell) {
+    return generateShellScript(shell);
+}
+export async function completionCommand(shellArg, options) {
+    if (options?.templates || shellArg === '--templates' || shellArg === '_templates') {
+        const templates = getTemplatesForCompletion();
+        if (templates.length > 0) {
+            console.log(templates.join('\n'));
+        }
+        return;
+    }
+    if (!shellArg) {
+        console.error('Error: Please specify a shell (bash, zsh, fish).');
+        process.exit(1);
+    }
+    try {
+        const script = generateCompletion(shellArg);
+        console.log(script);
+    }
+    catch (err) {
+        console.error(err.message || String(err));
+        process.exit(1);
+    }
+}
+// Allow direct execution via tsx src/commands/completionCommand.ts <shell>
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+    const shell = process.argv[2];
+    if (shell === '--templates' || shell === '_templates') {
+        completionCommand(shell, { templates: true });
+    }
+    else {
+        completionCommand(shell);
+    }
+}

package/dist/index.js

@@ -12,6 +12,7 @@ import { addCommand } from './commands/addCommand.js';
 import { removeCommand } from './commands/removeCommand.js';
 import { defaultPostConfigCommand } from './commands/defaultPostConfigCommand.js';
 import { securityResponseCommand } from './commands/securityResponseCommand.js';
+import { completionCommand } from './commands/completionCommand.js';
 import pkg from '../package.json' with { type: 'json' };
 const program = new Command();
 program
@@ -114,4 +115,11 @@ program
     .action(async (response) => {
     await securityResponseCommand(response);
 });
+program
+    .command('completion [shell]')
+    .description('Generate shell completion script')
+    .option('--templates', 'Internal helper to list template names for completion')
+    .action(async (shellArg, options) => {
+    await completionCommand(shellArg, options);
+});
 program.parse(process.argv);

package/doc/usage.md

@@ -305,3 +305,41 @@ To see your entire configuration (including all templates) in JSON format:
 ```bash
 pt config --json
 ```
+
+## Shell Completions
+
+`pt` can generate tab-completion scripts for Bash, Zsh, and Fish shells.
+
+### Installation
+
+#### Bash
+
+```bash
+pt completion bash > /etc/bash_completion.d/pt
+# Or user-local:
+pt completion bash > ~/.local/share/bash-completion/completions/pt
+```
+
+#### Zsh
+
+```bash
+pt completion zsh > ~/.zsh/completions/_pt
+# Add to ~/.zshrc:
+# fpath=(~/.zsh/completions $fpath)
+# autoload -U compinit && compinit
+```
+
+#### Fish
+
+```bash
+pt completion fish > ~/.config/fish/completions/pt.fish
+```
+
+### Dynamic Completion
+
+Template names auto-complete dynamically from your local `~/.pt/config.yaml` for:
+- `pt init <TAB>`
+- `pt update <TAB>`
+- `pt config <TAB>`
+- `pt remove <TAB>` (and `pt rm <TAB>`)
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garyr/pt-cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Project Template CLI - Learn structures and initialize projects",
   "main": "dist/index.js",
   "bin": {
@@ -13,6 +13,9 @@
     "dev": "tsx src/index.ts",
     "test": "node --import tsx --test tests/**/*.test.ts",
     "test:sequential": "node --import tsx --test tests/config.test.ts && node --import tsx --test tests/init.test.ts && node --import tsx --test tests/learn.test.ts && node --import tsx --test tests/substitute.test.ts && node --import tsx --test tests/config-utils.test.ts",
+    "completion:bash": "tsx src/commands/completionCommand.ts bash",
+    "completion:zsh": "tsx src/commands/completionCommand.ts zsh",
+    "completion:fish": "tsx src/commands/completionCommand.ts fish",
     "prepublishOnly": "npm run build",
     "build:linux": "bun build ./src/index.ts --compile --minify --target=bun-linux-x64   --outfile ../BUILD/pt-cli/pt-linux",
     "build:macos": "bun build ./src/index.ts --compile --minify --target=bun-darwin-x64  --outfile ../BUILD/pt-cli/pt-macos",

package/src/commands/completionCommand.ts

@@ -0,0 +1,415 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import YAML from 'yaml';
+import { getConfigPath } from '../config.js';
+
+export function getTemplatesForCompletion(): string[] {
+  try {
+    const configPath = getConfigPath();
+    if (!fs.existsSync(configPath)) {
+      return [];
+    }
+    const content = fs.readFileSync(configPath, 'utf-8');
+    if (!content.trim()) {
+      return [];
+    }
+    const parsed = YAML.parse(content);
+    if (!parsed || !parsed.templates || typeof parsed.templates !== 'object') {
+      return [];
+    }
+    return Object.keys(parsed.templates);
+  } catch {
+    return [];
+  }
+}
+
+export function generateBashCompletion(): string {
+  return `# Bash completion for pt
+_pt_completions() {
+  local cur prev words cword
+  if declare -F _init_completion >/dev/null 2>&1; then
+    _init_completion || return
+  else
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    words=("\${COMP_WORDS[@]}")
+    cword=$COMP_CWORD
+  fi
+
+  local commands="learn update init config ignore variables default-post-config add remove rm security-response completion"
+
+  # Complete top-level command or global flags
+  if [[ $cword -eq 1 ]]; then
+    if [[ "$cur" == -* ]]; then
+      COMPREPLY=( $(compgen -W "-v --version -h --help" -- "$cur") )
+    else
+      COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+    fi
+    return 0
+  fi
+
+  local cmd="\${words[1]}"
+
+  case "$cmd" in
+    learn)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--ignore -y --yes --name --desc --json --allow-untrusted -h --help" -- "$cur") )
+      fi
+      ;;
+    update)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--ignore -y --yes --desc --no-diff -h --help" -- "$cur") )
+      elif [[ $cword -eq 2 ]]; then
+        local templates
+        templates=$(pt completion --templates 2>/dev/null)
+        COMPREPLY=( $(compgen -W "$templates" -- "$cur") )
+      fi
+      ;;
+    init)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-f --file --skip-post-config --dry-run -y --yes --vars -h --help" -- "$cur") )
+      elif [[ $cword -eq 2 ]]; then
+        local templates
+        templates=$(pt completion --templates 2>/dev/null)
+        COMPREPLY=( $(compgen -W "$templates" -- "$cur") )
+      fi
+      ;;
+    config)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--json -h --help" -- "$cur") )
+      elif [[ $cword -eq 2 ]]; then
+        local templates
+        templates=$(pt completion --templates 2>/dev/null)
+        COMPREPLY=( $(compgen -W "$templates" -- "$cur") )
+      fi
+      ;;
+    ignore)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--set -h --help" -- "$cur") )
+      fi
+      ;;
+    variables)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--set --json --delete -h --help" -- "$cur") )
+      fi
+      ;;
+    default-post-config)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--set --json -h --help" -- "$cur") )
+      fi
+      ;;
+    add)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-f --file -h --help" -- "$cur") )
+      fi
+      ;;
+    remove|rm)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-y --yes -h --help" -- "$cur") )
+      elif [[ $cword -eq 2 ]]; then
+        local templates
+        templates=$(pt completion --templates 2>/dev/null)
+        COMPREPLY=( $(compgen -W "$templates" -- "$cur") )
+      fi
+      ;;
+    completion)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-h --help" -- "$cur") )
+      elif [[ $cword -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
+      fi
+      ;;
+    security-response)
+      if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "-h --help" -- "$cur") )
+      fi
+      ;;
+  esac
+}
+
+complete -F _pt_completions pt
+`;
+}
+
+export function generateZshCompletion(): string {
+  return `#compdef pt
+
+_pt_templates() {
+  local -a templates
+  templates=(\${(f)"$(pt completion --templates 2>/dev/null)"})
+  if [[ \${#templates[@]} -gt 0 ]]; then
+    _describe -t templates 'template' templates
+  fi
+}
+
+_pt() {
+  local context state state_policy
+  typeset -A opt_args
+
+  _arguments -C \\
+    '(-v --version)'{-v,--version}'[output the version number]' \\
+    '(-h --help)'{-h,--help}'[display help for command]' \\
+    '1: :->command' \\
+    '*:: :->args'
+
+  case $state in
+    command)
+      local -a commands
+      commands=(
+        'learn:Learn a project structure from an existing directory'
+        'update:Update an existing template with new structure/files'
+        'init:Initialize a new project from a learned template'
+        'config:Show current config location and list templates, or export a specific template'
+        'ignore:View or set global ignore patterns (comma-separated)'
+        'variables:View or set global variables (comma-separated key=value)'
+        'default-post-config:View or set default post-config tasks'
+        'add:Import/add a template from a JSON string or file'
+        'remove:Remove a learned template from the config'
+        'rm:Remove a learned template from the config'
+        'security-response:Handle security response from GUI'
+        'completion:Generate shell completion script'
+      )
+      _describe -t commands 'pt command' commands
+      ;;
+    args)
+      case $words[1] in
+        learn)
+          _arguments \\
+            '--ignore=[Folder patterns to ignore]:patterns:' \\
+            '(-y --yes)'{-y,--yes}'[Automatically confirm prompts]' \\
+            '--name=[Template name]:name:' \\
+            '--desc=[Template description]:description:' \\
+            '--json[Output template structure as JSON for sharing instead of saving]' \\
+            '--allow-untrusted[Bypass the trusted-source check for remote URLs]' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:path:_files -/'
+          ;;
+        update)
+          _arguments \\
+            '--ignore=[Folder patterns to ignore]:patterns:' \\
+            '(-y --yes)'{-y,--yes}'[Automatically confirm prompts]' \\
+            '--desc=[Template description]:description:' \\
+            '--no-diff[Disable additive mode, show full list]' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:template:_pt_templates' \\
+            '2:sourcePath:_files -/'
+          ;;
+        init)
+          _arguments \\
+            '(-f --file)'{-f,--file}'[Initialize directly from a JSON template file]:file:_files' \\
+            '--skip-post-config[Skip running post-config tasks]' \\
+            '--dry-run[Show what would be created without making changes]' \\
+            '(-y --yes)'{-y,--yes}'[Automatically answer yes to prompts]' \\
+            '--vars=[Comma-separated key=value variables]:variables:' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:template:_pt_templates' \\
+            '2:destPath:_files -/'
+          ;;
+        config)
+          _arguments \\
+            '--json[Output config or specific template as JSON]' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:template:_pt_templates'
+          ;;
+        ignore)
+          _arguments \\
+            '--set[Set the ignore patterns to the provided value]' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:patterns:'
+          ;;
+        variables)
+          _arguments \\
+            '--set[Set the variables to the provided pairs]' \\
+            '--json=[Set variables via JSON string or file]:data:' \\
+            '--delete=[Delete a specific global variable]:key:' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:pairs:'
+          ;;
+        default-post-config)
+          _arguments \\
+            '--set[Set the default post-config tasks via JSON]' \\
+            '--json=[JSON string or file containing tasks array]:data:' \\
+            '(-h --help)'{-h,--help}'[display help for command]'
+          ;;
+        add)
+          _arguments \\
+            '(-f --file)'{-f,--file}'[Path to JSON file containing template data]:file:_files' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:name:' \\
+            '2:json:'
+          ;;
+        remove|rm)
+          _arguments \\
+            '(-y --yes)'{-y,--yes}'[Automatically confirm removal]' \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:template:_pt_templates'
+          ;;
+        security-response)
+          _arguments \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:response:'
+          ;;
+        completion)
+          _arguments \\
+            '(-h --help)'{-h,--help}'[display help for command]' \\
+            '1:shell:(bash zsh fish)'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+if [[ "$(basename -- "$0")" != "_pt" ]]; then
+  compdef _pt pt 2>/dev/null || true
+fi
+`;
+}
+
+export function generateFishCompletion(): string {
+  return `# Fish completion for pt
+
+function __fish_pt_needs_command
+    set -l cmd (commandline -opc)
+    if [ (count $cmd) -eq 1 ]
+        return 0
+    end
+    return 1
+end
+
+function __fish_pt_using_command
+    set -l cmd (commandline -opc)
+    if [ (count $cmd) -gt 1 ]
+        if [ "$argv[1]" = "$cmd[2]" ]
+            return 0
+        end
+    end
+    return 1
+end
+
+function __fish_pt_templates
+    pt completion --templates 2>/dev/null
+end
+
+# Global options
+complete -c pt -n '__fish_pt_needs_command' -s v -l version -d 'output the version number'
+complete -c pt -n '__fish_pt_needs_command' -s h -l help -d 'display help for command'
+
+# Commands
+complete -c pt -n '__fish_pt_needs_command' -a learn -d 'Learn a project structure from an existing directory'
+complete -c pt -n '__fish_pt_needs_command' -a update -d 'Update an existing template with new structure/files'
+complete -c pt -n '__fish_pt_needs_command' -a init -d 'Initialize a new project from a learned template'
+complete -c pt -n '__fish_pt_needs_command' -a config -d 'Show current config location and list templates, or export a specific template'
+complete -c pt -n '__fish_pt_needs_command' -a ignore -d 'View or set global ignore patterns (comma-separated)'
+complete -c pt -n '__fish_pt_needs_command' -a variables -d 'View or set global variables (comma-separated key=value)'
+complete -c pt -n '__fish_pt_needs_command' -a default-post-config -d 'View or set default post-config tasks'
+complete -c pt -n '__fish_pt_needs_command' -a add -d 'Import/add a template from a JSON string or file'
+complete -c pt -n '__fish_pt_needs_command' -a remove -d 'Remove a learned template from the config'
+complete -c pt -n '__fish_pt_needs_command' -a rm -d 'Remove a learned template from the config'
+complete -c pt -n '__fish_pt_needs_command' -a security-response -d 'Handle security response from GUI'
+complete -c pt -n '__fish_pt_needs_command' -a completion -d 'Generate shell completion script'
+
+# learn
+complete -c pt -n '__fish_pt_using_command learn' -l ignore -d 'Folder patterns to ignore (comma-separated)'
+complete -c pt -n '__fish_pt_using_command learn' -s y -l yes -d 'Automatically confirm prompts'
+complete -c pt -n '__fish_pt_using_command learn' -l name -d 'Template name (skip prompt)'
+complete -c pt -n '__fish_pt_using_command learn' -l desc -d 'Template description (skip prompt)'
+complete -c pt -n '__fish_pt_using_command learn' -l json -d 'Output template structure as JSON for sharing instead of saving'
+complete -c pt -n '__fish_pt_using_command learn' -l allow-untrusted -d 'Bypass the trusted-source check for remote URLs'
+
+# update
+complete -c pt -n '__fish_pt_using_command update' -a '(__fish_pt_templates)' -d 'Template name'
+complete -c pt -n '__fish_pt_using_command update' -l ignore -d 'Folder patterns to ignore (comma-separated)'
+complete -c pt -n '__fish_pt_using_command update' -s y -l yes -d 'Automatically confirm prompts'
+complete -c pt -n '__fish_pt_using_command update' -l desc -d 'Template description (skip prompt)'
+complete -c pt -n '__fish_pt_using_command update' -l no-diff -d 'Disable additive mode, show full list'
+
+# init
+complete -c pt -n '__fish_pt_using_command init' -a '(__fish_pt_templates)' -d 'Template name'
+complete -c pt -n '__fish_pt_using_command init' -s f -l file -d 'Initialize directly from a JSON template file without adding it to local config'
+complete -c pt -n '__fish_pt_using_command init' -l skip-post-config -d 'Skip running post-config tasks'
+complete -c pt -n '__fish_pt_using_command init' -l dry-run -d 'Show what would be created without making changes'
+complete -c pt -n '__fish_pt_using_command init' -s y -l yes -d 'Automatically answer yes to prompts'
+complete -c pt -n '__fish_pt_using_command init' -l vars -d 'Comma-separated key=value variables'
+
+# config
+complete -c pt -n '__fish_pt_using_command config' -a '(__fish_pt_templates)' -d 'Template name'
+complete -c pt -n '__fish_pt_using_command config' -l json -d 'Output config or specific template as JSON'
+
+# ignore
+complete -c pt -n '__fish_pt_using_command ignore' -l set -d 'Set the ignore patterns to the provided value'
+
+# variables
+complete -c pt -n '__fish_pt_using_command variables' -l set -d 'Set the variables to the provided pairs'
+complete -c pt -n '__fish_pt_using_command variables' -l json -d 'Set variables via JSON string or file'
+complete -c pt -n '__fish_pt_using_command variables' -l delete -d 'Delete a specific global variable'
+
+# default-post-config
+complete -c pt -n '__fish_pt_using_command default-post-config' -l set -d 'Set the default post-config tasks via JSON'
+complete -c pt -n '__fish_pt_using_command default-post-config' -l json -d 'JSON string or file containing tasks array'
+
+# add
+complete -c pt -n '__fish_pt_using_command add' -s f -l file -d 'Path to JSON file containing template data'
+
+# remove / rm
+complete -c pt -n '__fish_pt_using_command remove' -a '(__fish_pt_templates)' -d 'Template name'
+complete -c pt -n '__fish_pt_using_command remove' -s y -l yes -d 'Automatically confirm removal'
+complete -c pt -n '__fish_pt_using_command rm' -a '(__fish_pt_templates)' -d 'Template name'
+complete -c pt -n '__fish_pt_using_command rm' -s y -l yes -d 'Automatically confirm removal'
+
+# completion
+complete -c pt -n '__fish_pt_using_command completion' -a 'bash zsh fish' -d 'Shell'
+`;
+}
+
+export function generateShellScript(shell: string): string {
+  switch (shell.toLowerCase()) {
+    case 'bash':
+      return generateBashCompletion();
+    case 'zsh':
+      return generateZshCompletion();
+    case 'fish':
+      return generateFishCompletion();
+    default: {
+      const supported = ['bash', 'zsh', 'fish'];
+      throw new Error(`Unsupported shell: ${shell}. Supported: ${supported.join(', ')}`);
+    }
+  }
+}
+
+export function generateCompletion(shell: string): string {
+  return generateShellScript(shell);
+}
+
+export async function completionCommand(shellArg?: string, options?: { templates?: boolean }): Promise<void> {
+  if (options?.templates || shellArg === '--templates' || shellArg === '_templates') {
+    const templates = getTemplatesForCompletion();
+    if (templates.length > 0) {
+      console.log(templates.join('\n'));
+    }
+    return;
+  }
+
+  if (!shellArg) {
+    console.error('Error: Please specify a shell (bash, zsh, fish).');
+    process.exit(1);
+  }
+
+  try {
+    const script = generateCompletion(shellArg);
+    console.log(script);
+  } catch (err: any) {
+    console.error(err.message || String(err));
+    process.exit(1);
+  }
+}
+
+// Allow direct execution via tsx src/commands/completionCommand.ts <shell>
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  const shell = process.argv[2];
+  if (shell === '--templates' || shell === '_templates') {
+    completionCommand(shell, { templates: true });
+  } else {
+    completionCommand(shell);
+  }
+}

package/src/index.ts

@@ -16,6 +16,7 @@ import { addCommand } from './commands/addCommand.js';
 import { removeCommand } from './commands/removeCommand.js';
 import { defaultPostConfigCommand } from './commands/defaultPostConfigCommand.js';
 import { securityResponseCommand } from './commands/securityResponseCommand.js';
+import { completionCommand } from './commands/completionCommand.js';
 
 import pkg from '../package.json' with { type: 'json' };
 
@@ -129,4 +130,12 @@ program
     await securityResponseCommand(response);
   });
 
+program
+  .command('completion [shell]')
+  .description('Generate shell completion script')
+  .option('--templates', 'Internal helper to list template names for completion')
+  .action(async (shellArg: string | undefined, options) => {
+    await completionCommand(shellArg, options);
+  });
+
 program.parse(process.argv);

package/tests/completion.test.ts

@@ -0,0 +1,210 @@
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import YAML from 'yaml';
+
+// Force a temporary home directory for testing before importing anything from the CLI
+const testHome = path.join(process.cwd(), '.test-home-completion');
+process.env.HOME = testHome;
+
+import {
+  generateCompletion,
+  generateBashCompletion,
+  generateZshCompletion,
+  generateFishCompletion,
+  getTemplatesForCompletion,
+  completionCommand,
+} from '../src/commands/completionCommand.js';
+import { getConfigPath, ensureConfigDir } from '../src/config.js';
+
+describe('Shell Completion Generation', () => {
+  beforeEach(() => {
+    ensureConfigDir();
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(testHome)) {
+      fs.rmSync(testHome, { recursive: true, force: true });
+    }
+  });
+
+  test('generateCompletion throws on unsupported shell', () => {
+    assert.throws(
+      () => generateCompletion('powershell'),
+      /Unsupported shell: powershell\. Supported: bash, zsh, fish/
+    );
+    assert.throws(
+      () => generateCompletion('elvish'),
+      /Unsupported shell: elvish\. Supported: bash, zsh, fish/
+    );
+  });
+
+  test('generateBashCompletion generates valid bash script with commands and flags', () => {
+    const script = generateBashCompletion();
+    assert.ok(script.includes('_pt_completions()'), 'Must define _pt_completions');
+    assert.ok(script.includes('complete -F _pt_completions pt'), 'Must register complete -F');
+    assert.ok(script.includes('pt completion --templates'), 'Must include template completion call');
+
+    const expectedCommands = [
+      'learn',
+      'update',
+      'init',
+      'config',
+      'ignore',
+      'variables',
+      'default-post-config',
+      'add',
+      'remove',
+      'rm',
+      'security-response',
+      'completion',
+    ];
+
+    for (const cmd of expectedCommands) {
+      assert.ok(script.includes(cmd), `Bash completion must include command ${cmd}`);
+    }
+
+    // Verify bash script parses cleanly and registers completion
+    try {
+      const tempScriptPath = path.join(testHome, 'pt-completion.bash');
+      fs.writeFileSync(tempScriptPath, script, 'utf-8');
+      const verifyOutput = execSync(`bash -c "source '${tempScriptPath}' && complete -p pt"`, { encoding: 'utf-8' });
+      assert.ok(verifyOutput.includes('_pt_completions pt'), 'complete -p pt should return registered function');
+    } catch (e: any) {
+      if (e.status !== undefined) throw e;
+    }
+  });
+
+  test('generateZshCompletion generates valid zsh script with commands and flags', () => {
+    const script = generateZshCompletion();
+    assert.ok(script.includes('#compdef pt'), 'Must include #compdef pt header');
+    assert.ok(script.includes('_pt()'), 'Must define _pt function');
+    assert.ok(script.includes('_pt_templates()'), 'Must define _pt_templates function');
+    assert.ok(script.includes('pt completion --templates'), 'Must call pt completion --templates');
+
+    const expectedCommands = [
+      'learn',
+      'update',
+      'init',
+      'config',
+      'ignore',
+      'variables',
+      'default-post-config',
+      'add',
+      'remove',
+      'rm',
+      'security-response',
+      'completion',
+    ];
+
+    for (const cmd of expectedCommands) {
+      assert.ok(script.includes(cmd), `Zsh completion must include command ${cmd}`);
+    }
+  });
+
+  test('generateFishCompletion generates valid fish script with commands and flags', () => {
+    const script = generateFishCompletion();
+    assert.ok(script.includes('complete -c pt'), 'Must include complete -c pt');
+    assert.ok(script.includes('__fish_pt_templates'), 'Must define __fish_pt_templates function');
+    assert.ok(script.includes('pt completion --templates'), 'Must call pt completion --templates');
+
+    const expectedCommands = [
+      'learn',
+      'update',
+      'init',
+      'config',
+      'ignore',
+      'variables',
+      'default-post-config',
+      'add',
+      'remove',
+      'rm',
+      'security-response',
+      'completion',
+    ];
+
+    for (const cmd of expectedCommands) {
+      assert.ok(script.includes(cmd), `Fish completion must include command ${cmd}`);
+    }
+  });
+
+  test('getTemplatesForCompletion returns template names when config exists', () => {
+    ensureConfigDir();
+    const configPath = getConfigPath();
+    const testConfig = {
+      version: '3.0',
+      templates: {
+        'web-app': { description: 'Web Application', folders: [] },
+        'python-cli': { description: 'Python CLI', folders: [] },
+        'godot-game': { description: 'Godot Game', folders: [] },
+      },
+    };
+    fs.writeFileSync(configPath, YAML.stringify(testConfig), 'utf-8');
+
+    const templates = getTemplatesForCompletion();
+    assert.deepStrictEqual(templates, ['web-app', 'python-cli', 'godot-game']);
+  });
+
+  test('getTemplatesForCompletion returns empty array when config does not exist', () => {
+    const configPath = getConfigPath();
+    if (fs.existsSync(configPath)) {
+      fs.unlinkSync(configPath);
+    }
+    const templates = getTemplatesForCompletion();
+    assert.deepStrictEqual(templates, []);
+  });
+
+  test('getTemplatesForCompletion returns empty array when config is empty or invalid', () => {
+    ensureConfigDir();
+    const configPath = getConfigPath();
+    fs.writeFileSync(configPath, '', 'utf-8');
+    assert.deepStrictEqual(getTemplatesForCompletion(), []);
+
+    fs.writeFileSync(configPath, ':::invalid yaml:::', 'utf-8');
+    assert.deepStrictEqual(getTemplatesForCompletion(), []);
+
+    fs.writeFileSync(configPath, YAML.stringify({ version: '3.0' }), 'utf-8');
+    assert.deepStrictEqual(getTemplatesForCompletion(), []);
+  });
+
+  test('completionCommand with --templates option outputs newline-separated template names', async () => {
+    ensureConfigDir();
+    const configPath = getConfigPath();
+    const testConfig = {
+      version: '3.0',
+      templates: {
+        'alpha-template': { description: 'Alpha', folders: [] },
+        'beta-template': { description: 'Beta', folders: [] },
+      },
+    };
+    fs.writeFileSync(configPath, YAML.stringify(testConfig), 'utf-8');
+
+    const logged: string[] = [];
+    const origLog = console.log;
+    console.log = (msg: any) => logged.push(String(msg));
+
+    try {
+      await completionCommand(undefined, { templates: true });
+      assert.strictEqual(logged.length, 1);
+      assert.strictEqual(logged[0], 'alpha-template\nbeta-template');
+    } finally {
+      console.log = origLog;
+    }
+  });
+
+  test('completionCommand with valid shell outputs script', async () => {
+    const logged: string[] = [];
+    const origLog = console.log;
+    console.log = (msg: any) => logged.push(String(msg));
+
+    try {
+      await completionCommand('bash');
+      assert.strictEqual(logged.length, 1);
+      assert.ok(logged[0].includes('_pt_completions()'));
+    } finally {
+      console.log = origLog;
+    }
+  });
+});