Update requesting orders

README.md

@@ -60,25 +60,33 @@ The email address and password you use should be the same as your login to
 [Planet Explorer](https://planet.com/explorer). The `auth init` command
 will automatically get your API key and store it locally.
 
-Now that you're initialized let's start with creating an order with the 
+Now that you're initialized let's start with creating an order request with the 
 Orders API:
 
 ```console
-$ planet orders create --name my-first-order --id <scene-ids> \ 
-    --item-type PSScene --bundle visual
+$ planet orders request --name my-first-order --id <scene-ids> \ 
+    --item-type PSScene --bundle visual > my_order.json
 ```
 
 You should supply a unique name after `--name` for each new order, to help
-you identify what oder. The `--id` is one or more scene ids (separated by
+you identify the order. The `--id` is one or more scene ids (separated by
 commas). These can be obtained from the data API, and you can also grab them
 from any search in Planet Explorer. Just be sure the scene id matches the
 [item-type](https://developers.planet.com/docs/apis/data/items-assets/#item-types) 
 to get the right type of image. And then be sure to specify a 
 [bundle](https://developers.planet.com/docs/orders/product-bundles-reference/).
 The most common ones are `visual` and `analytic`. 
 
+Next, you may create an order with the Orders API:
+```console
+$ planet orders create my_order.json
+```
 This will give you an order response JSON as shown in the 'example response' in
-[the Order API docs](https://developers.planet.com/docs/orders/ordering/#basic-ordering). 
+[the Order API docs](https://developers.planet.com/docs/orders/ordering/#basic-ordering). You may also pipe the `request` command to the `create` command to avoid the creation of a request.json file:
+```console
+$ planet orders request -name my-first-order --id <scene-ids> \ 
+    --item-type PSScene --bundle visual | planet orders create -
+```
 You can grab the `id` from that response, which will look something like 
 `dfdf3088-73a2-478c-a8f6-1bad1c09fa09`. You can then use that order-id in a 
 single command  to wait for the order and download it when you are ready:

planet/cli/orders.py

@@ -247,36 +247,53 @@ def read_file_json(ctx, param, value):
 @click.pass_context
 @translate_exceptions
 @coro
-@click.option('--name', required=True)
-@click.option('--id',
-              'ids',
-              help='One or more comma-separated item IDs',
-              type=click.STRING,
-              callback=split_list_arg,
-              required=True)
-# @click.option('--ids_from_search',
-#               help='Embedded data search')
+@click.argument("request", default="-", required=False)
+@pretty
+async def create(ctx, request: str, pretty):
+    '''  Create an order.
+
+    This command creates an order from an order request.
+    It outputs the created order description, optionally pretty-printed.
+
+    Arguments:
+
+    Order request as stdin, str, or file name. Full description of order
+    to be created.
+    '''
+    request_json = json.load(click.open_file(request))
+
+    async with orders_client(ctx) as cl:
+        order = await cl.create_order(request_json)
+
+    echo_json(order, pretty)
+
+
+@orders.command()
+@click.pass_context
+@translate_exceptions
+@coro
+@click.option('--name',
+              required=True,
+              help='Order name. Does not need to be unique.',
+              type=click.STRING)
 @click.option(
     '--bundle',
     multiple=False,
     required=True,
-    help='Specify bundle',
+    help='Product bundle.',
     type=click.Choice(planet.specs.get_product_bundles(),
                       case_sensitive=False),
 )
+@click.option('--id',
+              help='One or more comma-separated item IDs',
+              type=click.STRING,
+              callback=split_list_arg,
+              required=True)
 @click.option('--item-type',
               multiple=False,
               required=True,
               help='Specify an item type',
               type=click.STRING)
-@click.option('--email',
-              default=False,
-              is_flag=True,
-              help='Send email notification when Order is complete')
-@click.option('--cloudconfig',
-              help='Cloud delivery config json file.',
-              type=click.File('rb'),
-              callback=read_file_json)
 @click.option('--clip',
               help='Clip GeoJSON file.',
               type=click.File('rb'),
@@ -285,20 +302,35 @@ def read_file_json(ctx, param, value):
               help='Toolchain json file.',
               type=click.File('rb'),
               callback=read_file_json)
+@click.option('--email',
+              default=False,
+              is_flag=True,
+              help='Send email notification when Order is complete')
+@click.option(
+    '--cloudconfig',
+    help='Credentials for cloud storage provider to enable cloud delivery'
+    'of data.',
+    type=click.File('rb'),
+    callback=read_file_json)
 @pretty
-async def create(ctx,
-                 name,
-                 ids,
-                 bundle,
-                 item_type,
-                 email,
-                 cloudconfig,
-                 clip,
-                 tools,
-                 pretty):
-    '''Create an order.'''
+async def request(ctx,
+                  name,
+                  bundle,
+                  id,
+                  clip,
+                  tools,
+                  item_type,
+                  email,
+                  cloudconfig,
+                  pretty):
+    """Generate an order request.
+
+    This command provides support for building an order description used
+    in creating an order. It outputs the order request, optionally pretty-
+    printed.
+    """
     try:
-        product = planet.order_request.product(ids, bundle, item_type)
+        product = planet.order_request.product(id, bundle, item_type)
     except planet.specs.SpecificationException as e:
         raise click.BadParameter(e)
 
@@ -307,11 +339,6 @@ async def create(ctx,
     else:
         notifications = None
 
-    if cloudconfig:
-        delivery = planet.order_request.delivery(cloud_config=cloudconfig)
-    else:
-        delivery = None
-
     if clip and tools:
         raise click.BadParameter("Specify only one of '--clip' or '--tools'")
     elif clip:
@@ -322,13 +349,15 @@ async def create(ctx,
 
         tools = [planet.order_request.clip_tool(clip)]
 
+    if cloudconfig:
+        delivery = planet.order_request.delivery(cloud_config=cloudconfig)
+    else:
+        delivery = None
+
     request = planet.order_request.build_request(name,
                                                  products=[product],
                                                  delivery=delivery,
                                                  notifications=notifications,
                                                  tools=tools)
 
-    async with orders_client(ctx) as cl:
-        order = await cl.create_order(request)
-
-    echo_json(order, pretty)
+    echo_json(request, pretty)