---
phase: 06-developer-experience
plan: 06-03
type: execute
---

<objective>
Implement shell completion for workflow names, project names, and file paths to improve CLI usability.

Purpose: Enable tab completion in shells (bash, zsh, fish) for dynamic values from the n8n API and local filesystem, making commands faster and more discoverable.
Output: Working shell completion functions integrated into all relevant commands with installation instructions.
</objective>

<execution_context>
~/.claude/get-shit-done/workflows/execute-phase.md
./summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/06-developer-experience/06-01-SUMMARY.md
@.planning/phases/06-developer-experience/06-02-SUMMARY.md
@REQUIREMENTS.md (lines 776-871: Shell Completion specification)
@src/n8n_cli/cli.py (note: add_completion=False, needs to be enabled)
@src/n8n_cli/client/core.py (APIClient for fetching workflows/projects)
@src/n8n_cli/commands/workflow.py (workflow commands needing completion)
@src/n8n_cli/commands/project.py (project commands needing completion)

**Key insight from REQUIREMENTS.md:**
- Typer has built-in shell completion support (not Click)
- Completion functions use autocompletion parameter, not shell_complete
- Must enable completion in Typer app: add_completion=True or install command
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create shell completion functions</name>
  <files>src/n8n_cli/completion.py</files>
  <action>
    Create new file src/n8n_cli/completion.py with three completion functions following Typer patterns:

    **1. complete_workflows(ctx: typer.Context, incomplete: str) -> List[str]:**
    - Import APIClient and load_config from client module
    - Try/except block (return empty list on any error)
    - Load config, create APIClient
    - Check ctx.params for "project" parameter (if exists, filter by project)
    - Call client.workflows.list(project_id=project_id if project else None)
    - Return list of workflow names that start with incomplete (case-insensitive)

    **2. complete_projects(ctx: typer.Context, incomplete: str) -> List[str]:**
    - Try/except block (return empty list on error)
    - Load config, create APIClient
    - Call client.projects.list()
    - Return list of project names that start with incomplete (case-insensitive)

    **3. complete_workflow_files(ctx: typer.Context, incomplete: str) -> List[str]:**
    - Import Path from pathlib
    - Try/except block (return empty list on error)
    - Parse incomplete to get directory and prefix
    - If incomplete is directory: search in that dir
    - Else: search in parent dir with filename prefix
    - Return list of .json files and directories (directories with "/" suffix)
    - Filter by incomplete prefix

    **Notes:**
    - All functions return List[str] (Typer completion format, not CompletionItem)
    - Silent failure (empty list) on errors - completion shouldn't break commands
    - Case-insensitive matching for better UX
    - Follow REQUIREMENTS.md patterns (lines 799-860) but adapt for Typer syntax
  </action>
  <verify>
    python -c "from n8n_cli.completion import complete_workflows, complete_projects, complete_workflow_files; print('OK')"
    ruff check src/n8n_cli/completion.py passes
  </verify>
  <done>Three completion functions implemented and importable without errors</done>
</task>

<task type="auto">
  <name>Task 2: Integrate completion into commands</name>
  <files>src/n8n_cli/cli.py, src/n8n_cli/commands/workflow.py, src/n8n_cli/commands/project.py, src/n8n_cli/commands/member.py</files>
  <action>
    **Enable completion in main app (cli.py):**
    - Change `add_completion=False` to `add_completion=True` in Typer() initialization
    - This enables `n8n --install-completion` and `n8n --show-completion` commands

    **Add completion to workflow commands (workflow.py):**
    - Import: `from n8n_cli.completion import complete_workflows, complete_workflow_files`
    - workflow view: Add `autocompletion=complete_workflows` to name argument
    - workflow activate/deactivate: Add `autocompletion=complete_workflows` to name argument
    - workflow delete: Add `autocompletion=complete_workflows` to name argument
    - workflow move: Add `autocompletion=complete_workflows` to name argument, `autocompletion=complete_projects` to destination argument
    - workflow diff: Add `autocompletion=complete_workflow_files` to file argument
    - workflow push: Add `autocompletion=complete_workflow_files` to files argument
    - workflow create: Add `autocompletion=complete_workflow_files` to file argument
    - workflow pull: Add `autocompletion=complete_workflows` to names argument (variadic)

    **Add completion to project commands (project.py):**
    - Import: `from n8n_cli.completion import complete_projects`
    - project view: Add `autocompletion=complete_projects` to name argument

    **Add completion to member commands (member.py):**
    - Import: `from n8n_cli.completion import complete_projects`
    - member list: Add `autocompletion=complete_projects` to project argument
    - member add: Add `autocompletion=complete_projects` to project argument
    - member remove: Add `autocompletion=complete_projects` to project argument

    **Notes:**
    - Use autocompletion parameter (Typer), not shell_complete (Click)
    - Test that imports don't break commands (completion failures should be silent)
    - Don't add completion to execution commands (execution IDs not practical for completion)
    - Don't add completion to user commands (emails not completable)
  </action>
  <verify>
    n8n --help shows --install-completion and --show-completion options
    pytest tests/commands/test_workflow.py tests/commands/test_project.py tests/commands/test_member.py passes
    ruff check src/n8n_cli/ passes
  </verify>
  <done>Completion enabled in app and integrated into all relevant command arguments</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Shell completion system for workflows, projects, and files</what-built>
  <how-to-verify>
    1. Install completion:
       ```bash
       n8n --install-completion
       # Follow shell-specific instructions (may need to restart shell)
       ```

    2. Test workflow completion (requires n8n instance configured):
       ```bash
       n8n workflow view <TAB>
       # Should show workflow names from your instance
       ```

    3. Test project completion:
       ```bash
       n8n project view <TAB>
       # Should show project names
       ```

    4. Test file completion:
       ```bash
       n8n workflow diff <TAB>
       # Should show .json files and directories
       ```

    5. Test error handling (without config):
       ```bash
       # Temporarily rename config to test graceful failure
       mv ~/.config/n8n-cli/config ~/.config/n8n-cli/config.bak
       n8n workflow view <TAB>
       # Should complete without error (even if no suggestions)
       mv ~/.config/n8n-cli/config.bak ~/.config/n8n-cli/config
       ```

    6. Verify help text:
       ```bash
       n8n --help | grep -i completion
       # Should show --install-completion and --show-completion
       ```
  </how-to-verify>
  <resume-signal>Type "approved" if completion works as expected, or describe issues to fix</resume-signal>
</task>

<task type="auto">
  <name>Task 3: Add completion documentation to README</name>
  <files>README.md</files>
  <action>
    Add shell completion section to README.md (create section after installation/configuration):

    ```markdown
    ## Shell Completion

    Enable tab completion for workflows, projects, and file paths:

    ### Installation

    **Automatic (recommended):**
    ```bash
    n8n --install-completion
    ```

    Follow the shell-specific instructions. You may need to restart your shell.

    **Manual setup:**

    **Bash:**
    ```bash
    eval "$(n8n --show-completion bash)"
    # Add to ~/.bashrc for persistence
    ```

    **Zsh:**
    ```bash
    eval "$(n8n --show-completion zsh)"
    # Add to ~/.zshrc for persistence
    ```

    **Fish:**
    ```bash
    n8n --show-completion fish > ~/.config/fish/completions/n8n.fish
    ```

    ### What Gets Completed

    - **Workflow names:** `n8n workflow view <TAB>` shows your workflows
    - **Project names:** `n8n project view <TAB>` shows your projects
    - **File paths:** `n8n workflow diff <TAB>` shows .json files
    ```

    Insert this section after the Configuration section and before Usage Examples (or at end if no Usage section exists).
  </action>
  <verify>
    README.md contains Shell Completion section with installation instructions
    ruff check passes (if README has Python code blocks with <!-- prettier-ignore -->)
  </verify>
  <done>README.md documents shell completion installation and usage</done>
</task>

</tasks>

<verification>
Before declaring plan complete:
- [ ] completion.py exists with three completion functions
- [ ] cli.py has add_completion=True
- [ ] Relevant commands have autocompletion parameter
- [ ] `n8n --help` shows completion options
- [ ] Manual test: completion works in zsh/bash/fish
- [ ] Manual test: completion fails gracefully without config
- [ ] README.md documents shell completion
- [ ] All tests passing
</verification>

<success_criteria>

- Shell completion functions implemented for workflows, projects, and files
- Completion integrated into all relevant commands
- Completion enabled in Typer app (--install-completion available)
- Graceful error handling (completion never breaks commands)
- Documentation added to README
- Manual testing confirms completion works in at least one shell
- Phase 6 complete - all developer experience features implemented
  </success_criteria>

<output>
After completion, create `.planning/phases/06-developer-experience/06-03-SUMMARY.md`:

# Phase 6 Plan 3: Shell Completion Summary

**[Substantive one-liner - what shipped, not "phase complete"]**

## Accomplishments

- Dynamic shell completion for workflow and project names from n8n API
- File path completion for .json workflow files
- Completion integrated into workflow, project, and member commands
- Graceful error handling (silent failures don't break completion)
- Installation documentation in README

## Files Created/Modified

- `src/n8n_cli/completion.py` - Three completion functions
- `src/n8n_cli/cli.py` - Enabled completion in Typer app
- `src/n8n_cli/commands/workflow.py` - Added completion to arguments
- `src/n8n_cli/commands/project.py` - Added completion to arguments
- `src/n8n_cli/commands/member.py` - Added completion to arguments
- `README.md` - Shell completion documentation

## Decisions Made

[Document implementation choices, e.g., which commands got completion vs which didn't]

## Issues Encountered

[Problems and resolutions, or "None"]

## Next Step

**Phase 6 complete!** All developer experience features implemented:
- ✅ Utility functions (detect_project_context, save_workflow, etc.)
- ✅ Progressive verbosity (standardized count=True across all commands)
- ✅ Shell completion (workflows, projects, files)

Ready for **Phase 7: Quality & Testing** - comprehensive test suite and pre-commit hooks.
</output>
