Doctrine CLI and additional things like Migrations

The documentation for both migrations and ORM state about the $cli object. However, it is never explained how the $cli object is instanciated.

It isn't obvious that $cli is either defined by the doctrine command (=doctrine.php which comes with the sandbox and is eventually installed system-wide) or actually needs to be defined by the developer himself. It might be obvious when you read the complete manual first (like a book, which actually nobody does - at least not anybody I know), but this isn't helpful because the manuals are all reference manuals.

So the manuals need to be changed so that it actually explains where $cli comes from.

http://www.doctrine-project.org/docs/orm/2.1/en/reference/tools.html
http://www.doctrine-project.org/projects/migrations/2.0/docs/reference/introduction/en#introduction

As there's no code - at least not which I could have found easily - to add CLI commands to system's doctrine.php without modifying it, developers are forced to duplicate the code of doctrine.php and add their own CLI commands.

The problem could be easily avoided by allowing the users to define something like $additionalCommands in their cli-config.php which could then appended via $cli->addCommands() in the master doctrine.php file.