diff --git a/README.md b/README.md
index 3e9523f..425e25b 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
 # mev-inspect
-A [WIP] Ethereum MEV Inspector in Python
+A [WIP] Ethereum MEV Inspector in Python managed by Poetry
 
 ## Containers
 mev-inspect's local setup is built on [Docker Compose](https://docs.docker.com/compose/)
@@ -12,44 +12,64 @@ By default it starts up:
 ## Running locally
 Setup [Docker](https://www.docker.com/products/docker-desktop)
 
-Start the services with Docker Compose
+Start the services (optionally as background processes)
 ```
-docker compose up
-```
-or to run in the background
-```
-docker compose up -d
+poetry run start [-b]
 ```
 
 To stop the services (if running in the background, otherwise just ctrl+c)
 ```
-docker compose down
+poetry run stop
 ```
 
-Check `docker compose help` for more tools available
+MEV container can be attached via
+```
+poetry run attach
+```
+
+Running additional compose commands are possible through standard `docker
+compose ...` calls.  Check `docker compose help` for more tools available
 
 ## Executing scripts
-To run a command, prefix it with
+Inspection is the only simplified api available through poetry at the moment
+with a more generalized api on the horizon.
+
+Inspect scripts must have `-script`, `-block_number` and `-rpc` arguments.
+Using the uniswap inspect from `./examples`
 ```
-docker compose exec mev-inspect <YOUR COMMAND>
+poetry run inspect -script ./examples/uniswap_inspect.py -block_number 11931271 \
+                   -rpc 'http://111.11.11.111:8545'
 ```
 
-For example, to run `testing_file.py`:
+Generalized user defined scripts can still be run through the docker interface as
 ```
 docker compose exec mev-inspect python testing_file.py \
     -block_number 11931271 \
     -rpc 'http://111.11.11.111:8545'
 ```
+### Poetry Scripts
+```bash
+# code check
+poetry run lint # linting via Pylint
+poetry run test # testing and code coverage with Pytest
+poetry run isort # fixing imports 
+poetry run mypy # type checking 
+poetry run black # style guide 
+poetry run pre-commit # runs Black, PyLint and MyPy
+# docker management
+poetry run start [-b] # starts all services, optionally in the background
+poetry run stop # shutsdown all services or just ctrl + c if foreground
+poetry run build # rebuilds containers
+poetry run attach # enters the mev-inspect container in interactive mode
+# launches inspection script
+poetry run inspect -script ... -block_number ... -rpc ...
+```
 
-Or to run the tests:
-```
-docker compose exec mev-inspect python -m unittest tests/*py
-```
 
 ## Rebuilding containers
 After changes to the app's Dockerfile, rebuild with
 ```
-docker compose build
+poetry run build
 ```
 
 ## Using PGAdmin
@@ -63,34 +83,26 @@ docker compose build
     - user / password: see `.env`
 
 ## Contributing
-Contributing requires installing the pre-commit hooks
+Development can be done locally or in the docker container.  Use local if
+contributions can be fully tested without invoking the database related
+services.
 
-1 . Ensure you're using python 3.9
-
-If not, [pyenv](https://github.com/pyenv/pyenv) is a great option for managing python versions
-
-2. Create a virtualenv
+1. Install dependencies and build python environment
 ```
-python3 -m venv venv
+poetry install
 ```
-
-3. Activate it
+or with docker
 ```
-. venv/bin/activate
+poetry run build
 ```
-(exit with `deactivate`)
-
-4. Install dev libraries
+2. Pre-commit is used to maintain a consistent style, prevent errors and ensure
+   test coverage.  Make sure to fix any errors presented via Black, Pylint and
+   MyPy pre-commit hooks
 ```
-pip install -r requirements_dev.txt
+poetry run pre-commit --all-files
 ```
-
-5. Install pre-commit
-```
-pre-commit install
-```
-
-6. Install pre-commit's dependencies and ensure it's working
+or within docker
 ```
 pre-commit run --all-files
 ```
+3. Update README if needed