---
phase: 04-execution-management
plan: 04-02
type: execute
---

<objective>
Implement execution list and view CLI commands for inspecting workflow execution results.

Purpose: Enable users to list recent executions (with filtering) and view detailed execution information from the terminal.
Output: Working `n8n execution list` and `n8n execution view` commands with comprehensive test coverage.
</objective>

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

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/04-execution-management/04-CONTEXT.md
@.planning/phases/04-execution-management/04-01-SUMMARY.md
@.planning/phases/03-workflow-management/03-02-SUMMARY.md
@src/n8n_cli/commands/workflow.py
@src/n8n_cli/client/resources/executions.py
@src/n8n_cli/client/core.py
@src/n8n_cli/config.py
@tests/commands/test_workflow.py

**Phase 3 CLI command patterns to follow:**
- Typer command groups with @app.command() decorators
- Config validation (check api_key and instance_url presence)
- Flexible input resolution (workflow names, IDs, or file paths)
- Error handling with `raise typer.Exit(1) from None` (no stack traces)
- Color-coded output (typer.style for status)
- Comprehensive test coverage using pytest fixtures

**CONTEXT.md priorities:**
1. Post-execution forensics (understanding what happened)
2. Clear visibility into failures (errors, which step failed)
3. Consistent UX with workflow commands

**REQUIREMENTS.md specs:**
- `execution list [WORKFLOW]` - List executions with filters
  - Optional workflow argument (name, ID, or file path)
  - --limit/-n flag (default: 20)
  - --status flag (success/error/running/waiting)
  - Format: `[ID] status workflow_id timestamp workflow_name`

- `execution view <ID>` - View execution details
  - Required execution ID argument
  - --data/-d flag to include full execution data
  - -v/-vv for verbosity (stack traces with -vv)
  - Show: ID, workflow, status, started, finished, mode
  - With --data: show node failures, error messages, stack traces
</context>

<tasks>

<task type="auto" tdd="true">
  <name>Task 1: Create execution list command with filtering</name>
  <files>src/n8n_cli/commands/execution.py, tests/commands/test_execution.py, src/n8n_cli/cli.py</files>
  <test-first>
    Test: execution list command displays executions correctly
    Cases:
    - list() shows executions with aligned columns (ID, status, workflow_id, timestamp, workflow_name)
    - list() with no args uses default limit=20
    - list(workflow="My Workflow") resolves workflow name to ID and filters
    - list(workflow="abc123") uses ID directly if it looks like an ID
    - list --limit 10 limits results
    - list --status error filters by status
    - list() handles API errors gracefully (no stack traces)
    - list() checks config validation (api_key, instance_url)
  </test-first>
  <action>
    Create execution command group and list command:

    1. Create src/n8n_cli/commands/execution.py:
       - Import typer, APIClient, Config, datetime
       - Create app = typer.Typer() for execution command group
       - Create @app.command("list") function

    2. list(workflow: str | None = None, limit: int = 20, status: str | None = None) command:
       - Load config with Config.load()
       - Validate config (api_key and instance_url required)
       - Create APIClient context manager
       - If workflow argument provided:
         - Try to resolve as ID first (12-20 chars alphanumeric pattern from Phase 3)
         - If not ID-like or get() fails, resolve via workflows.find_by_name()
       - Call client.executions.list(workflow_id=resolved_id, limit=limit, status=status)
       - Display results in aligned columns:
         - Format: `  [ID] status  workflow_id  timestamp  workflow_name`
         - Color-code status: GREEN for success, RED for error, YELLOW for running/waiting
         - Use workflow_id from execution (workflow_name not in API response - show ID for now)
       - Handle errors gracefully: typer.echo() error message, raise typer.Exit(1) from None

    3. Register in cli.py:
       - Import execution_group from commands.execution
       - main.add_command(execution_group, "execution")

    4. Create comprehensive tests:
       - Mock Config.load() and APIClient
       - Test filtering by workflow (name and ID resolution)
       - Test limit and status parameters
       - Test error handling (API errors, config errors)
       - Test output formatting

    Note: Since Execution model doesn't include workflow name (only workflow_id), just display the ID for now. Phase 5 may enhance this with workflow name lookup.
  </action>
  <verify>
    pytest tests/commands/test_execution.py::TestExecutionList -v passes
    mypy src/n8n_cli/commands/execution.py passes
    ruff check src/n8n_cli/commands/execution.py passes
  </verify>
  <done>
    - execution list command implemented with workflow/limit/status filtering
    - Command follows Phase 3 patterns (config validation, error handling, testing)
    - Tests verify all filtering scenarios and error cases
    - Output is color-coded and well-formatted
  </done>
</task>

<task type="auto" tdd="true">
  <name>Task 2: Create execution view command with data flag</name>
  <files>src/n8n_cli/commands/execution.py, tests/commands/test_execution.py</files>
  <test-first>
    Test: execution view command displays execution details
    Cases:
    - view("exec_id") shows basic execution info (ID, workflow_id, status, started, finished, mode)
    - view("exec_id", data=True) includes full execution data
    - view with -d/--data flag shows error details when status=error
    - view with -vv shows stack traces for errors
    - view() handles NotFoundError gracefully (execution doesn't exist)
    - view() handles API errors with clean error messages
  </test-first>
  <action>
    Add view command to execution.py:

    @app.command("view")
    def view(execution_id: str, data: bool = False, verbose: int = 0):
       - Load config and validate
       - Create APIClient context manager
       - Call client.executions.get(execution_id, include_data=data)
       - Display execution details:
         - Basic info (always shown):
           - Execution ID: {id}
           - Workflow: {workflow_id}
           - Status: {status} (color-coded)
           - Started: {started_at}
           - Finished: {finished_at or "N/A"}
           - Mode: {mode}
         - With --data flag (data=True):
           - If status == "error":
             - Show "Error Details:" section
             - Extract error from execution.data (varies by n8n version)
             - Show error message, node that failed
             - With verbose >= 2 (-vv): show stack trace if available
       - Handle NotFoundError: "Execution {id} not found"
       - Handle other errors gracefully (no stack traces)

    Tests:
    - Mock APIClient.executions.get() responses
    - Test basic view (no --data)
    - Test view with --data for success and error executions
    - Test verbosity levels for stack traces
    - Test error handling (404, API errors)

    Note: execution.data structure varies by n8n version. Extract what's available, don't fail if structure differs. Focus on status, basic error info.
  </action>
  <verify>
    pytest tests/commands/test_execution.py::TestExecutionView -v passes
    All quality gates pass: pytest (all execution command tests), mypy, ruff
  </verify>
  <done>
    - execution view command implemented with --data and verbosity support
    - Command displays clear execution details
    - Error information extracted and displayed for failed executions
    - Tests verify all scenarios (basic, with data, errors, verbosity)
    - Both list and view commands complete and tested
  </done>
</task>

</tasks>

<verification>
Before declaring plan complete:
- [ ] pytest tests/commands/test_execution.py passes (all tests green)
- [ ] mypy src/n8n_cli/commands/ passes with no errors
- [ ] ruff check src/n8n_cli/ passes with no violations
- [ ] Manual test: n8n execution list works
- [ ] Manual test: n8n execution view <id> works
- [ ] Manual test: n8n execution view <id> --data works
</verification>

<success_criteria>

- execution command group registered in CLI
- list command with workflow/limit/status filtering
- view command with --data and verbosity flags
- Color-coded output for execution status
- Comprehensive error handling (no stack traces)
- All tests passing with good coverage
- Commands follow Phase 3 patterns
  </success_criteria>

<output>
After completion, create `.planning/phases/04-execution-management/04-02-SUMMARY.md`:

# Phase 4 Plan 2: List and View Commands Summary

**[Substantive one-liner - what shipped]**

## Accomplishments

- execution list command with filtering
- execution view command with --data flag
- Color-coded status output
- Comprehensive test coverage

## Files Created/Modified

- `src/n8n_cli/commands/execution.py` - Execution command group with list/view
- `tests/commands/test_execution.py` - Test suite for execution commands
- `src/n8n_cli/cli.py` - Register execution command group

## Decisions Made

[Document any technical decisions or deviations from plan]

## Issues Encountered

[Problems and resolutions, or "None"]

## Next Step

Ready for 04-03-PLAN.md (Download and Retry Commands)
</output>
