adding .run() method with docs and test. fixes #1