Debugging Terminal Deploys: devops-rewind Enables Rewind, Branching, and Breakpoints

I Built a Terminal Session Debugger with Rewind, Breakpoints, and Branching

Lakshmi Sravya Vedantham developed devops-rewind to eliminate the need to restart 50-step deployment processes from scratch when a single command fails. The tool captures command-level metadata including stdout, stderr, exit codes, and working directories to enable stateful debugging.

Why This Matters

Technical reality often involves long, fragile deployment sequences where a failure at step 47 results in 45 minutes of wasted time or risky manual recovery. While ideal models suggest perfectly idempotent scripts, devops-rewind provides a practical safety net by treating terminal sessions like Git repositories, allowing for branching and state-aware rewinding that raw terminal recorders like script cannot provide.

Key Insights

• Command-level recording via subprocess.run() ensures portability across macOS, Linux, and Windows while providing structured exit codes for every step.
• Unlike script or asciinema, devops-rewind understands individual command boundaries, enabling features like step-by-step replay and divergence-point detection.
• Conditional breakpoints can pause replays based on specific patterns, non-zero exit codes, or explicit step numbers.
• The branching engine uses a fork strategy that copies parent steps 0 through N into a new session object, preserving history without modifying the original record.
• The tool features an 89% test coverage across a Python 3.9-3.12 matrix and uses SQLite for persistent, portable session storage.

Working Examples

Basic workflow to record and rewind a deployment session.

pip install devops-rewind
devops-rewind record my-deploy
devops-rewind rewind my-deploy 45

Advanced usage for error-triggered breakpoints and session branching.

devops-rewind breakpoint add my-deploy --on-error
devops-rewind branch my-deploy 1 --exec
devops-rewind diff my-deploy my-deploy-branch-1

Internal implementation of the session branching logic.

def branch_session(session, from_step, storage, name=None):
    steps = session.steps[: from_step + 1]
    branch = Session.new(name or f"{session.name}-branch-{from_step}")
    branch.steps = [step.copy() for step in steps]
    branch.parent_id = session.session_id
    branch.branch_point = from_step
    storage.save(branch)
    return branch

Practical Applications

• Use Case: Debugging Kubernetes deployments by rewinding to a specific ConfigMap application step and branching to test environment variable fixes without re-building images.
• Pitfall: Relying on raw terminal output recorders like script which do not capture exit codes, resulting in manual verification overhead during troubleshooting.
• Use Case: Exporting successful terminal branches into runnable shell scripts or Markdown documentation to streamline CI/CD pipeline creation.

References:

• https://dev.to/lakshmisravyavedantham/i-built-a-terminal-session-debugger-with-rewind-breakpoints-and-branching-3gka
• https://github.com/LakshmiSravyaVedantham/devops-rewind