docs(cli): add dedicated README for the cli (#388)

README.md

@@ -35,23 +35,7 @@ that leverage the COSCRAD API. The Many ideas explored in the community projects
 will eventually find their way into Coscrad's core.
 
 **COSCRAD CLI**
-We also have built our own command-line interface, `COSCRAD CLI`. This is used
-for administrative tasks like dumping data snapshots (in persistence layer, domain layer
-and view layer formats), seeding test data and restoring data dumps, dumping
-a JSON version of schemas for our domain models, view models, command and event payloads,
-and so on.
-
-Currently, `COSCRAD CLI` is part of the `api`, and it is available via a custom
-build of the `api`. Run `npx nx build:api:cli` to build the `COSCRAD CLI`. The
-cli will be built to `dist/apps/cosccrad-cli`. Run
-
-```
-node main.js <command> <options>
-```
-
-from within this directory to execute a `COSCRAD CLI` command.
-
-<!-- TODO Add documentation for all commands -->
+The `coscrad-cli` is a command line tool for data administration tasks. Its use is documented [here](./apps/api/cli.README.md)
 
 In the future, once our domain has been moved to a separate lib, we will move
 the `COSCRAD CLI` to a standalone app in the mono-repo.

apps/api/cli.README.md

@@ -0,0 +1,60 @@
+# TODO Break `coscrad-cli` out into a separate app
+
+# COSCRAD CLI
+
+## About
+
+`coscrad-cli` is a command line tool for data administration.
+
+## Usage
+
+### Building and Running
+
+To build `coscrad-cli`, run
+
+> > > npx run api:build:cli
+
+To run `coscrad-cli`, run
+
+> > > node dist/apps/coscrad-cli/main.js <command-name> <command-options>
+
+For example,
+
+> > > node dist/apps/coscrad-cli/main.js data-dump -f mybackup.data.json
+
+You will need to copy a `production.env` to the directory you run the cli from.
+Any data dumps will be to the working directory. Note that we often use the
+format <{prefix}.data.json> for convenience, because any `*.data.json` is
+git ignored in our project.
+
+### Options:
+
+> > > -h, --help
+
+display help for command
+
+### Commands:
+
+> > > data-dump [-f {filename} | --filename={filename}]
+
+dumps the database state to a snapshot file
+
+> > > data-restore [-f {filename} | --filename={filename}]
+
+restores the database state from a snapshot file
+
+> > > list-migrations
+
+lists available database migrations
+
+> > > run-migrations
+
+runs all available database migrations
+
+> > > revert-latest-migration
+
+reverts the most recently run migration, if there is one
+
+> > > validate-invariants
+
+reports invariant validation for all aggregate root instances