+CLI UI

README.md

@@ -39,3 +39,38 @@
 * rejected/abandoned: not in main, inactive
 * submitted is equal to {unreviewed or abandoned}
 * unsubmitted
+
+### CLI user interface
+
+reviewed changes all have two identifiers: their publishing (-> "unreviewed") revision (`pub#[0-9]+`)
+and the position in `main`, `main#[0-9]+`; there also exist local changes (`local#[0-9]+`).
+exclusion only based upon stuff in branch; inclusion only based upon publishing revision.
+A change belongs to a single server.
+
+it is possible to define pre-diff hooks (e.g. auto-format all code) and post-apply hooks (e.g. run CI)
+
+```console
+// user-local "remote" registration
+// maybe use workspaces?
+$ byr remote add [--dup=full|latest] $RNAME $URL
+[$ byr remote set [--dup=full|latest] $RNAME]
+
+// pulls data from remoe explicitly,
+// should be usually unnecessary
+$ byr fetch [$RNAME]
+
+// removes the content of $DIR and replaces it with the current content of $BRANCH
+$ byr co|checkout [-C $DIR] [-R $RNAME] [-B $BRANCH] [-I $LIST_OF_ADDITIONALLY_INCLUDED_CHANGES] [-E $LIST_OF_EXCLUDED_CHANGES]
+
+// applies a patch script to a checkout, recording that in a change
+$ byr a[pply] -m "change description" -s $PATCH_SCRIPT
+
+// translates the current change into a diff, recording that in a change
+$ byr a[pply] -m "change description" --diff
+
+// upload newer changes to $RNAME
+$ byr pub[lish] $RNAME
+
+// mark a change as private to prevent it from being pushed to any server
+$ byr private $CHANGE_ID
+```