> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slomo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: Record and Replay Your First Python Crash

> Install Slomo, add two lines to your Python app, trigger a crash, and explore the recording with the CLI — all in about five minutes, no account needed.

This guide walks you through installing Slomo, wiring it into a Python app, and using the CLI to find and diagnose a real crash — all in about five minutes. You don't need an account, a running server, or any external infrastructure.

<Steps>
  <Step title="Install Slomo">
    Install Slomo from PyPI into your active environment:

    ```bash theme={null}
    pip install slomo
    ```

    Slomo requires Python 3.12 or later. If you're on an older version, see the [Installation](/installation) page for guidance.
  </Step>

  <Step title="Add two lines to your app">
    Import `slomo` and call `enable()` at the very top of your application's entry point — before any other application code runs:

    ```python theme={null}
    import slomo          # [!code ++]
    slomo.enable()        # [!code ++]
    ```

    That's the entire integration. From this point on, Slomo automatically records:

    * Every function call in your project code
    * Unhandled exceptions, including local variables from the crashing frame
    * SQL queries (sqlite3, SQLAlchemy, and compatible ORMs)
    * HTTP requests made with `requests` or `httpx`
    * Log records at `WARNING` level and above
    * Session metadata: argv, cwd, Python version, hostname, PID, and exit status
  </Step>

  <Step title="Run your app and trigger a crash">
    To see Slomo in action, save the following as `app.py` in an empty directory and run it. The script has a deliberate bug — `checkout()` crashes when the requested SKU is missing from the database.

    ```python app.py theme={null}
    import sqlite3
    import slomo
    from slomo import track

    slomo.enable()

    @track
    def load_inventory(db, sku):
        return db.execute(
            "SELECT sku, qty FROM inventory WHERE sku = ?", (sku,)
        ).fetchone()

    @track
    def checkout(db, sku):
        inventory = load_inventory(db, sku)
        return {"sku": inventory[0], "qty": inventory[1]}  # BUG: inventory can be None

    db = sqlite3.connect(":memory:")
    db.execute("CREATE TABLE inventory (sku TEXT PRIMARY KEY, qty INTEGER)")
    db.execute("INSERT INTO inventory VALUES ('widget', 5)")

    checkout(db, "widget")  # succeeds
    checkout(db, "gadget")  # crashes — 'gadget' is not in the database
    ```

    ```bash theme={null}
    python app.py
    ```

    When the script exits (even after a crash), Slomo writes the full session recording to `.slomo/` in the current directory. The directory is created automatically on the first run.
  </Step>

  <Step title="Explore the recording with the CLI">
    With the recording on disk, use the Slomo CLI to understand what went wrong.

    **List all recorded crashes:**

    ```bash theme={null}
    slomo issues
    ```

    ```console theme={null}
    ┃ issue        ┃ title                                      ┃ category       ┃ count ┃
    │ SM-8b6f710a  │ TypeError: 'NoneType' object is not subsc… │ Null Reference │     5 │
    ```

    Slomo groups crashes by fingerprint so you can see at a glance which issues are recurring and how often.

    **Get a root-cause diagnosis:**

    ```bash theme={null}
    slomo doctor SM-8b6f710a
    ```

    ```console theme={null}
    Category              Null Reference  (95% confidence)
    Occurrences           5  (5 unhandled) across 5 session(s)
    Likely root cause     TypeError raised in checkout() at app.py:14.
                          Variable 'inventory' was None at the crash site.
    First bad function    checkout()
    First bad variable    inventory
    Suggested fix         Guard against None before the failing access at app.py:14
                          — trace where the value is produced and handle the missing case.
    Context just before the crash:
      13:04:52.133 sql.query   SELECT sku, qty FROM inventory WHERE sku = ?
      13:04:52.133 sql.result  0 rows, 9µs
    ```

    `slomo doctor` pinpoints the first function and variable that went wrong, explains why the crash happened, and suggests a fix — all from the local recording, with no network call.

    **Step through the crash interactively:**

    ```bash theme={null}
    slomo replay SM-8b6f710a
    ```

    The `replay` command opens an interactive terminal UI that lets you step forward and backward through every function call, inspect arguments and return values, and see exactly how the program reached the crash.
  </Step>
</Steps>

## Next steps

<Note>
  Run `slomo init` in your project directory to scaffold a `.slomo/config.toml` file with all available options and inline comments. This is optional — Slomo works without any configuration — but useful when you want to tune what gets recorded or where sessions are stored.
</Note>

Now that you've seen Slomo in action, here's where to go next:

* **[Installation](/installation)** — pip/uv/pipx setup, Python version requirements, and optional integrations
* **[Core Concepts](/concepts/how-it-works)** — understand how `sys.monitoring` and PEP 669 power zero-config instrumentation
* **[CLI Reference](/reference/cli/overview)** — full documentation for every Slomo command