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

# plog run

> Wrap a Python agent with automatic instrumentation

`plog run` wraps any Python command with automatic framework instrumentation. No code changes required.

## Usage

```bash theme={null}
plog run -- python my_agent.py
plog run --agent-id my-agent -- python -m my_package
plog run --db /tmp/audit.db -- python script.py
plog run --server http://localhost:7600 -- python agent.py
```

## Flags

| Flag         | Default                  | Description                                 |
| ------------ | ------------------------ | ------------------------------------------- |
| `--agent-id` | `auto`                   | Agent identifier for audit events           |
| `--db`       | `~/.provenlog/events.db` | SQLite path (embedded mode)                 |
| `--server`   | —                        | Server URL (mutually exclusive with `--db`) |

## How it works

1. Creates a temporary `sitecustomize.py` that imports `provenlog.auto`
2. Modifies `PYTHONPATH` to include the temporary file
3. Executes your command as a child process
4. Python runs `sitecustomize` on startup, patching all detected frameworks
5. stdin/stdout/stderr are forwarded transparently
6. Signals (SIGINT, SIGTERM) are forwarded to the child
7. The child's exit code is preserved

## Examples

```bash theme={null}
# Basic usage
plog run -- python my_agent.py

# With custom agent ID
plog run --agent-id payment-agent -- python -m payment_processor

# With custom database
plog run --db /var/log/audit.db -- python my_agent.py

# Sending events to a server
plog run --server http://localhost:7600 -- python my_agent.py
```

See [Auto-Instrumentation](/integrations/auto-instrumentation) for details on which frameworks are detected and how patching works.