Skip to content

How-To: Terminal Sessions and Operational Commands

This page provides concrete terminal workflows you can copy/paste.

1. Docs Build Validation

.venv/bin/mkdocs build --strict

Example output:

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: .../site
INFO    -  Documentation built in 0.67 seconds

2. Focused Test Run (No Coverage Gate)

For quick local checks:

PYTHONPATH=src .venv/bin/python -m pytest -q tests/test_config.py --no-cov

Example output:

collected 3 items

tests/test_config.py ...                                                 [100%]

============================== 3 passed in 0.02s ===============================

3. Why a single test file may fail under default coverage settings

If you run a subset with coverage enabled:

PYTHONPATH=src .venv/bin/python -m pytest -q tests/test_config.py

You may hit global fail-under threshold because only a small module slice was exercised.

Use full suite for release-quality coverage checks.

4. Runtime Data and Certificate Checks

Check local certificate artifacts:

ls -la ~/.mitmproxy

Check whether monitor listener exists:

lsof -iTCP:8080 -sTCP:LISTEN

Check system proxy dictionary (macOS):

scutil --proxy

5. Release-Oriented Command Sequence

  1. Full tests:
PYTHONPATH=src .venv/bin/python -m pytest -q
  1. Docs strict build:
.venv/bin/mkdocs build --strict
  1. Build desktop artifacts:
python build.py --name SafeModeSecurity --clean --zip
  1. macOS DMG build (if on macOS):
python build.py --name SafeModeSecurity --clean --zip --dmg

6. Troubleshooting Command Outcomes

Command Healthy Outcome If Not
mkdocs build --strict exits 0, no warnings promoted to errors fix links/nav/page references
pytest -q all tests pass inspect failing module and recent changes
lsof -iTCP:8080 listener present when monitor ON monitor process failed to boot
scutil --proxy proxy keys appear when proxy ON OS proxy not set or monitor not ready