chore(cli): change name of --output option to --format

CHANGELOG.md

@@ -16,6 +16,15 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## 📚 Documentation -->
 
+# [0.10.1] - 2022-11-28
+
+## 🚀 Features
+
+- **Replace the '--output' option type with '--format' - @gocamille, #1413 fixes #1212**
+
+  This change adds the new option, `--format`, to allow users to define the format type for messages printed to `stdout` (either by passing `plain` or `json` as an argument to `--format`). This replaces the use of `--output` for defining format types. The `--output` option will be available to define the output file type instead, following [Command Line Interface Guidelines for file outputs](https://clig.dev/#:~:text=%2Do%2C%20%2D%2Doutput%3A%20Output%20file.%20For%20example%2C%20sort%2C%20gcc.). This is an additive, non-breaking change and using the `--output` option will continue to be valid.
+
+
 # [0.10.0] - 2022-11-10
 
 > Important: 1 potentially breaking change below, indicated by **❗ BREAKING ❗**

README.md

@@ -69,11 +69,17 @@ Options:
   -l, --log <LOG_LEVEL>
           Specify Rover's log level
 
+      --format <FORMAT_TYPE>
+          Specify Rover's format type
+
+          [default: plain]
+          [possible values: plain, json]
+
       --output <OUTPUT_TYPE>
           Specify Rover's output type
 
           [default: plain]
-          [possible values: plain, json]
+          [possible values: plain, json, filename]
 
       --insecure-accept-invalid-certs
           Accept invalid certificates when performing HTTPS requests.

crates/rover-std/src/emoji.rs

@@ -20,6 +20,7 @@ pub enum Emoji {
     Skull,
     Compose,
     Warn,
+    Memo,
 }
 
 impl Emoji {
@@ -42,6 +43,7 @@ impl Emoji {
             Skull => "💀 ",
             Compose => "🎶 ",
             Warn => "⚠️  ",
+            Memo => "📝 ",
         }
     }
 }

docs/source/commands/graphs.mdx

@@ -63,7 +63,7 @@ You can also save the output to a local `.graphql` file like so:
 
 ```bash
 # Creates prod-schema.graphql or overwrites if it already exists
-rover graph fetch my-graph@my-variant > prod-schema.graphql
+rover graph fetch my-graph@my-variant --output prod-schema.graphql
 ```
 
 > For more on passing values via `stdout`, see [Conventions](../conventions#using-stdout).

docs/source/commands/readmes.mdx

@@ -29,13 +29,13 @@ By default, the README is output to `stdout`. You can also save the output to a
 
 ```bash
 # Creates README.md or overwrites if it already exists
-rover readme fetch my-graph@my-variant > README.md
+rover readme fetch my-graph@my-variant --output README.md
 ```
 
-You can also request the output as JSON with the `--output json` option:
+You can also request the output as JSON with the `--format json` option:
 
 ```bash
-rover readme fetch my-graph@my-variant --output json
+rover readme fetch my-graph@my-variant --format json
 ```
 
 > For more on passing values via `stdout`, see [Conventions](../conventions#using-stdout).

docs/source/commands/subgraphs.mdx

@@ -54,7 +54,7 @@ The subgraph must be reachable by Rover. The subgraph does _not_ need to have in
 
 #### Watching for schema changes
 
-If you pass `--watch` to `rover subgraph introspect`, Rover introspects your subgraph every second. Whenever the returned schema differs from the _previously_ returned schema, Rover outputs the updated schema.  
+If you pass `--watch` to `rover subgraph introspect`, Rover introspects your subgraph every second. Whenever the returned schema differs from the _previously_ returned schema, Rover outputs the updated schema. This is most useful when combined with the `--output <OUTPUT_FILE>` argument which will write the introspection response out to a file whenever its contents change.
 
 #### Including headers
 
@@ -83,7 +83,7 @@ You can also save the output to a local `.graphql` file like so:
 
 ```bash
 # Creates accounts-schema.graphql or overwrites if it already exists
-rover subgraph introspect http://localhost:4000 > accounts-schema.graphql
+rover subgraph introspect http://localhost:4000 --output accounts-schema.graphql
 ```
 
 > For more on passing values via `stdout`, see [Using `stdout`](../conventions#using-stdout).

docs/source/commands/supergraphs.mdx

@@ -105,7 +105,7 @@ You can save the schema output to a local `.graphql` file like so:
 
 ```bash
 # Creates prod-schema.graphql or overwrites if it already exists
-rover supergraph compose --config ./supergraph.yaml > prod-schema.graphql
+rover supergraph compose --config ./supergraph.yaml --output prod-schema.graphql
 ```
 
 > For more on passing values via `stdout`, see [Using `stdout`](../conventions#using-stdout).

docs/source/configuring.md

@@ -74,17 +74,24 @@ rover graph check my-graph@prod --schema ./schema.graphql --log debug
 If Rover log messages are unhelpful or unclear, please leave us feedback in an
 [issue on GitHub](https://github.com/apollographql/rover/issues/new/choose)!
 
-## Output format
-
-### `--output plain` (default)
+## Configuring output
 
 By default, Rover prints the main output of its commands to `stdout` in plaintext. It also prints a _descriptor_ for that output to `stderr` if it thinks it's being operated by a human (it checks whether the terminal is TTY).
 
-> For more on `stdout`, see [Conventions](./conventions/#using-stdout).
+> For more on `stdout`, see [Conventions](https://chat.openai.com/conventions/#using-stdout).
+
+Every Rover command supports two options for configuring its output behavior:
+
+- `--format`, for [setting the output format](#setting-output-format) (`plain` or `json`)
+- `--output`, for [writing a command's output to a file](#setting-output-location) instead of `stdout`
 
-### `--output json`
+### JSON output
 
-For more programmatic control over Rover's output, you can pass `--output json` to any command. Rover JSON output has the following minimal structure:
+> **Note:** The `--format` option was added in Rover v0.11.0. Earlier versions of Rover use the `--output` option to set output format.
+>
+> Current versions of Rover still support using `--output` this way, but that support is deprecated and will be removed in a future release.
+
+For more programmatic control over Rover's output, you can pass `--format json` to any command. Rover JSON output has the following minimal structure:
 
 ```json title="success_example"
 {
@@ -232,7 +239,21 @@ This particular `error` object includes `details` about what went wrong. Notice
 
 #### Example `jq` script
 
-You can combine the `--output json` flag with the [`jq`](https://stedolan.github.io/jq/) command line tool to create powerful custom workflows. For example, [this gist](https://gist.github.com/EverlastingBugstopper/d6aa0d9a49bcf39f2df53e1cfb9bb88a) demonstrates converting output from `rover {sub}graph check my-graph --output json` to Markdown.
+You can combine the `--format json` flag with the [`jq`](https://stedolan.github.io/jq/) command line tool to create powerful custom workflows. For example, [this gist](https://gist.github.com/EverlastingBugstopper/d6aa0d9a49bcf39f2df53e1cfb9bb88a) demonstrates converting output from `rover {sub}graph check my-graph --format json` to Markdown.
+
+### Writing to a file
+
+The `--output` option enables you to specify a file destination for writing a Rover command's output:
+
+```bash
+rover supergraph compose --output ./supergraph-schema.graphql --config ./supergraph.yaml
+```
+
+If the specified file already exists, Rover overwrites it.
+
+> **Note:** This functionality is available in Rover v0.11.0 and later. In _earlier_ versions of Rover, the `--output` option instead provides the functionality that's now provided by the [`--format` option](#json-output). 
+>
+> Current versions of Rover still support using `--output` like `--format`, but that support is deprecated and will be removed in a future release.
 
 ## Setting config storage location
 

docs/source/conventions.md

@@ -39,9 +39,9 @@ All Rover commands that interact with the Apollo graph registry require a graph
 
 ### Using `stdout`
 
-Rover commands print to `stdout` in a predictable, portable format. This enables output to be used elsewhere (such as in another CLI, or as input to another Rover command). To help maintain this predictability, Rover prints logs to `stderr` instead of `stdout`.
+Rover commands print to `stdout` in a predictable, portable format. This enables output to be used elsewhere (such as in another CLI, or as input to another Rover command). To help maintain this predictability, Rover prints progress logs to `stderr` instead of `stdout`.
 
-To redirect Rover's output to a location other than your terminal, you can use the pipe `|` or output redirect `>` operators.
+To redirect Rover's output to a location other than your terminal, you can use the `--output <OUTPUT_FILE>` argument, the pipe `|` operator, or the redirect `>` operator.
 
 #### Pipe `|`
 
@@ -53,12 +53,12 @@ rover graph introspect http://localhost:4000 | pbcopy
 
 In this example, the output of the `introspect` command is piped to `pbcopy`, a MacOS command that copies a value to the clipboard. Certain Rover commands also accept values from `stdin`, as explained in [Using `stdin`](#using-stdin).
 
-#### Output redirect `>`
+#### Output to a file
 
-Use the output redirect operator to write the `stdout` of a command to a file, like so:
+Use the `--output <OUTPUT_FILE>` argument to write command output to a file. 
 
 ```
-rover graph fetch my-graph@prod > schema.graphql
+rover graph fetch my-graph@prod --output schema.graphql
 ```
 
 In this example, the schema returned by `graph fetch` is written to the file `schema.graphql`. If this file already exists, it's overwritten. Otherwise, it's created.
@@ -72,5 +72,3 @@ rover graph introspect http://localhost:4000 | rover graph check my-graph --sche
 ```
 
 In this example, the schema returned by `graph introspect` is then passed as the `--schema` option to `graph check`.
-
-> Currently, `--schema` is the only Rover option that accepts a file path.

docs/source/migration.md

@@ -144,9 +144,9 @@ As a workaround, you might be able to use `cat` to combine multiple files and pa
 
 ### Machine-readable output
 
-In the Apollo CLI, many commands support alternate output formatting options, such as `--json` and `--markdown`. Currently, Rover only supports `--output json`, and leaves markdown formatting up to the consumer. For more information on JSON output in Rover, see [these docs](./configuring/#--output-json).
+In the Apollo CLI, many commands support alternate output formatting options, such as `--json` and `--markdown`. Currently, Rover only supports `--format json`, and leaves markdown formatting up to the consumer. For more information on JSON output in Rover, see [these docs](./configuring/#json-output).
 
-An example script for converting output from `rover {sub}graph check my-graph --output json` can be found in [this gist](https://gist.github.com/EverlastingBugstopper/d6aa0d9a49bcf39f2df53e1cfb9bb88a).
+An example script for converting output from `rover {sub}graph check my-graph --format json` can be found in [this gist](https://gist.github.com/EverlastingBugstopper/d6aa0d9a49bcf39f2df53e1cfb9bb88a).
 
 ## Examples
 
@@ -160,8 +160,8 @@ An example script for converting output from `rover {sub}graph check my-graph --
 apollo client:download-schema --graph my-graph --variant prod
 
 ## Rover ##
-# automatically outputs to stdout. Can redirect to schema.graphql
-rover graph fetch my-graph@prod > schema.graphql
+# automatically outputs to stdout. Can redirect to schema.graphql with the `--output <OUTPUT_FILE>` argument
+rover graph fetch my-graph@prod --output schema.graphql
 ```
 
 ### Fetching a graph's schema from introspection
@@ -173,9 +173,9 @@ rover graph fetch my-graph@prod > schema.graphql
 apollo service:download --endpoint http://localhost:4000
 
 ## Rover ##
-# automatically outputs to stdout. Can redirect to schema.graphql
+# automatically outputs to stdout. Can redirect to schema.graphql with the `--output <OUTPUT_FILE>` argument
 # can ONLY output SDL
-rover graph introspect http://localhost:4000
+rover graph introspect http://localhost:4000 --output schema.graphql
 ```
 
 ### Publishing a monolithic schema to the Apollo graph registry
@@ -261,8 +261,6 @@ rover graph introspect http://localhost:4001 --header "authorization: Bearer wxy
 | rover graph check my-graph@prod --schema -
 ```
 
-
-
 ### Pushing Subgraph Changes (with a config file)
 
 ```js

src/bin/rover.rs

@@ -2,13 +2,13 @@ use robot_panic::setup_panic;
 use rover::cli::Rover;
 
 #[calm_io::pipefail]
-fn main() -> std::io::Result<()> {
+fn main() -> Result<_, std::io::Error> {
     setup_panic!(Metadata {
         name: rover::PKG_NAME.into(),
         version: rover::PKG_VERSION.into(),
         authors: rover::PKG_AUTHORS.into(),
         homepage: rover::PKG_HOMEPAGE.into(),
         repository: rover::PKG_REPOSITORY.into()
     });
-    Rover::run_from_args()
+    Ok(Rover::run_from_args())
 }

src/cli.rs

@@ -4,8 +4,8 @@ use lazycell::{AtomicLazyCell, LazyCell};
 use reqwest::blocking::Client;
 use serde::Serialize;
 
-use crate::command::output::JsonOutput;
 use crate::command::{self, RoverOutput};
+use crate::options::OutputOpts;
 use crate::utils::{
     client::{ClientBuilder, ClientTimeout, StudioClientConfig},
     env::{RoverEnv, RoverEnvKey},
@@ -61,9 +61,8 @@ pub struct Rover {
     #[serde(serialize_with = "option_from_display")]
     log_level: Option<Level>,
 
-    /// Specify Rover's output type
-    #[arg(long = "output", default_value = "plain", global = true)]
-    output_type: OutputType,
+    #[clap(flatten)]
+    output_opts: OutputOpts,
 
     /// Accept invalid certificates when performing HTTPS requests.
     ///
@@ -110,13 +109,14 @@ pub struct Rover {
 }
 
 impl Rover {
-    pub fn run_from_args() -> io::Result<()> {
+    pub fn run_from_args() -> RoverResult<()> {
         Rover::parse().run()
     }
 
-    pub fn run(&self) -> io::Result<()> {
+    pub fn run(&self) -> RoverResult<()> {
         timber::init(self.log_level);
         tracing::trace!(command_structure = ?self);
+        self.output_opts.validate_options();
 
         // attempt to create a new `Session` to capture anonymous usage data
         let rover_output = match Session::new(self) {
@@ -152,20 +152,13 @@ impl Rover {
 
         match rover_output {
             Ok(output) => {
-                match self.output_type {
-                    OutputType::Plain => output.print()?,
-                    OutputType::Json => JsonOutput::from(output).print()?,
-                }
+                self.output_opts.handle_output(output)?;
+
                 process::exit(0);
             }
             Err(error) => {
-                match self.output_type {
-                    OutputType::Json => JsonOutput::from(error).print()?,
-                    OutputType::Plain => {
-                        tracing::debug!(?error);
-                        error.print()?;
-                    }
-                }
+                self.output_opts.handle_output(error)?;
+
                 process::exit(1);
             }
         }
@@ -199,15 +192,15 @@ impl Rover {
                 self.get_client_config()?,
                 self.get_git_context()?,
                 self.get_checks_timeout_seconds()?,
-                self.get_json(),
+                &self.output_opts,
             ),
             Command::Template(command) => command.run(self.get_client_config()?),
             Command::Readme(command) => command.run(self.get_client_config()?),
             Command::Subgraph(command) => command.run(
                 self.get_client_config()?,
                 self.get_git_context()?,
                 self.get_checks_timeout_seconds()?,
-                self.get_json(),
+                &self.output_opts,
             ),
             Command::Update(command) => {
                 command.run(self.get_rover_config()?, self.get_reqwest_client()?)
@@ -220,10 +213,6 @@ impl Rover {
         }
     }
 
-    pub(crate) fn get_json(&self) -> bool {
-        matches!(self.output_type, OutputType::Json)
-    }
-
     pub(crate) fn get_rover_config(&self) -> RoverResult<Config> {
         let override_home: Option<Utf8PathBuf> = self
             .get_env_var(RoverEnvKey::ConfigHome)?
@@ -411,13 +400,19 @@ pub enum Command {
 }
 
 #[derive(ValueEnum, Debug, Serialize, Clone, Eq, PartialEq)]
-pub enum OutputType {
+pub enum RoverOutputFormatKind {
     Plain,
     Json,
 }
 
-impl Default for OutputType {
+#[derive(ValueEnum, Debug, Serialize, Clone, Eq, PartialEq)]
+pub enum RoverOutputKind {
+    RoverOutput,
+    RoverError,
+}
+
+impl Default for RoverOutputFormatKind {
     fn default() -> Self {
-        OutputType::Plain
+        RoverOutputFormatKind::Plain
     }
 }