Clean Mode¶

Clear the terminal screen before each restart for a cleaner development experience.

What is Clean Mode?¶

Clean mode clears the terminal screen every time your application restarts, providing a fresh view of the output.

Usage¶

Command Line¶

pyreload --clean app.py

Or use the short flag:

pyreload -c app.py

Config File¶

clean: true

How It Works¶

Without Clean Mode (Default)¶

[pyreload] starting: python app.py
Server running on port 8000
Request: GET /api/users

[pyreload] restarting due to changes in: src/app.py
[pyreload] starting: python app.py
Server running on port 8000
Request: GET /api/users

Output accumulates, making it harder to see current state.

With Clean Mode¶

[screen clears]
[pyreload] restarting due to changes in: src/app.py
[pyreload] starting: python app.py
Server running on port 8000

Each restart shows only new output.

When to Use Clean Mode¶

Good Use Cases¶

Development servers: Web applications with startup messages
Single-run scripts: Scripts that produce complete output each run
Status dashboards: Applications that display current state
Clean logs: When you only care about the latest execution

Not Recommended For¶

Debugging: When you need to see previous error messages
Cumulative output: When tracking changes across restarts
Log aggregation: When collecting historical output
CI/CD: Automated environments where history matters

Examples¶

Flask Development¶

pyreload --clean app.py

Output shows only current server state:

[pyreload] starting: python app.py
 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://127.0.0.1:5000

Django Development¶

pyreload --clean manage.py runserver

Clean output on each reload:

[pyreload] starting: python manage.py runserver
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

CLI Application¶

pyreload --clean script.py

Shows only latest run results:

[pyreload] starting: python script.py
Processing 100 records...
✓ Success: All records processed
Time: 2.3s

Combined with Other Options¶

With Verbose Mode¶

pyreload --clean --verbose app.py

Shows Pyreload details with clean restarts:

[pyreload] watching: src/**/*.py
[pyreload] changes detected in: src/app.py
[pyreload] restarting...
[pyreload] starting: python app.py
Server running on port 8000

With Delay¶

pyreload --clean --delay 2 app.py

Clears screen after delay period.

With Config File¶

clean: true
verbose: true
delay: 1.0
watch:
  - src
extensions:
  - py

Interactive Clear¶

You can also manually clear the screen while Pyreload is running:

Press c to clear without restarting:

[lots of output...]

c  <-- Press 'c'

[screen cleared, app continues running]

Terminal Compatibility¶

Clean mode works on most terminals:

✅ Linux (bash, zsh, fish)
✅ macOS (Terminal.app, iTerm2)
✅ Windows (PowerShell, CMD, Windows Terminal)
✅ CI/CD environments

Pyreload uses ANSI escape codes or clear/cls commands depending on the platform.

Alternatives¶

Manual Clear Command¶

Instead of clean mode:

pyreload app.py

Press c when you want to clear.

Logging to File¶

Keep history while having clean screen:

pyreload --clean app.py 2>&1 | tee app.log

Screen stays clean, logs saved to app.log.

Terminal Scrollback¶

Use terminal's scrollback buffer:

Most terminals: Shift + PageUp
tmux: Ctrl+b then [
iTerm2: Cmd+Shift+h

Best Practices¶

Development: Use clean mode for cleaner output
Debugging: Disable clean mode to see error history
Presentations: Enable clean mode for demos
Production: Don't use in production monitoring

Troubleshooting¶

"Screen doesn't clear"¶

Check terminal compatibility:

# Test if clear command works
clear

If this doesn't work, your terminal may not support clearing.

"Need to see previous output"¶

Disable clean mode:

pyreload app.py  # without --clean

Or use logging:

pyreload --clean app.py 2>&1 | tee output.log

"Clear is too aggressive"¶

Use manual clear instead:

pyreload app.py
# Press 'c' only when needed