From f90fb427b9203bacf4a5a8561dbced93987ac980 Mon Sep 17 00:00:00 2001
From: Robert Carlsen <rwcarlsen@gmail.com>
Date: Wed, 13 Apr 2016 10:43:53 -0500
Subject: [PATCH] extend archetype cli flag discussion a bit

---
 source/arche/cli.rst | 55 ++++++++++++++++++++++++++++++++++++++------
 source/cep/cep21.rst |  2 ++
 2 files changed, 50 insertions(+), 7 deletions(-)

diff --git a/source/arche/cli.rst b/source/arche/cli.rst
index fef6e9c4d..58bf08255 100644
--- a/source/arche/cli.rst
+++ b/source/arche/cli.rst
@@ -3,9 +3,16 @@
 Archetype Command Line Interface
 =======================================
 
-Many of the archetype-specific |Cyclus| CLI commands are automatically generated
-if the Cyclus preprocessor is used. For example, member variables added with
-``#pragma cyclus var`` are added to the generated input XML schema, e.g., 
+There are a few archetype-specific |Cyclus| CLI commands that allow
+introspecting details of archetypes that |Cyclus| can find.  Most expose data
+that is automatically generated by the Cyclus preprocessor. For example,
+member variables added with ``#pragma cyclus var`` are added to the generated
+input XML schema.  Agents are referenced on the command line by their
+single-string form ``spec`` (e.g. ``:cycamore:Source``) which is discussed
+:ref:`here <agent-spec-docs>`.
+
+To view the auto-generated XML schema used for validating archetype
+configuration parameters in input files:
 
   .. code-block:: bash
 
@@ -24,13 +31,47 @@ if the Cyclus preprocessor is used. For example, member variables added with
 	  </element>
       </interleave>
 
-However, other CLI interactions exist if they are implemented on the archetype.
+To view a JSON structured output of all the data generated and collected from
+``#pragma cyclus`` annotations for a particular archetype:
+
+  .. code-block:: bash
+
+      $ cyclus --agent-annotations :cycamore:Source
+      {
+       "all_parents": [
+        "cyclus::Agent", 
+        "cyclus::Facility", 
+        "cyclus::Ider", 
+        "cyclus::StateWrangler", 
+        "cyclus::TimeListener", 
+        "cyclus::Trader", 
+        "cyclus::toolkit::AgentManaged", 
+        "cyclus::toolkit::CommodityProducer"
+       ], 
+       "doc": "This facility acts as a source of material with a fixed...
+       ...
+
+And to list all archetypes inside a particular library:
+
+  .. code-block:: bash
+
+      $ cyclus --agent-listing :cycamore
+      :cycamore:DeployInst
+      :cycamore:Enrichment
+      :cycamore:FuelFab
+      :cycamore:GrowthRegion
+      :cycamore:ManagerInst
+      :cycamore:Reactor
+      :cycamore:Separations
+      :cycamore:Sink
+      :cycamore:Source
+      :cycamore:Storage
 
 Archetype Versioning
 --------------------
 
-The ``cyclus::Agent`` class exposes a ``version()`` member function which is
-queried by the |Cyclus| CLI. For example, 
+The ``cyclus::Agent`` class exposes a ``version()`` member function which can be
+queried with the |Cyclus| CLI. For example, 
 
   .. code-block:: bash
 
@@ -49,5 +90,5 @@ and then access the version with
 
   .. code-block:: bash
 
-      $ cyclus --agent-version my_package:my_library:MyArchetype
+      $ cyclus --agent-version my/path:my_library:MyArchetype
       My Version
diff --git a/source/cep/cep21.rst b/source/cep/cep21.rst
index e9c4d3fe6..e5f719755 100644
--- a/source/cep/cep21.rst
+++ b/source/cep/cep21.rst
@@ -21,6 +21,8 @@ in a desired location and then identify specific agents in them to |Cyclus|.
 This CEP explains where modules can/should be installed and how |Cyclus| finds
 and identifies agents in them.
 
+.. _agent-spec-docs:
+
 Agent Spec
 ===========