From bda05103bc4e5325d4a9254ef016d8f218a4fafd Mon Sep 17 00:00:00 2001
From: Robert Fratto <robert.fratto@grafana.com>
Date: Wed, 18 Mar 2020 13:18:56 -0400
Subject: [PATCH] sync logcli.md with command output

---
 docs/getting-started/logcli.md | 103 ++++++++++++---------------------
 1 file changed, 37 insertions(+), 66 deletions(-)

diff --git a/docs/getting-started/logcli.md b/docs/getting-started/logcli.md
index b6530ba78d16..545a4d38a03d 100644
--- a/docs/getting-started/logcli.md
+++ b/docs/getting-started/logcli.md
@@ -94,7 +94,9 @@ Flags:
                          LOKI_CLIENT_CERT_PATH env var.
       --key=""           Path to the client certificate key. Can also be set
                          using LOKI_CLIENT_KEY_PATH env var.
-      --org-id=ORG-ID    org ID header to be substituted for auth
+      --org-id=ORG-ID    adds X-Scope-OrgID to API requests for representing
+                         tenant ID. Useful for requesting tenant data when
+                         bypassing an auth gateway.
 
 Commands:
   help [<command>...]
@@ -103,13 +105,19 @@ Commands:
   query [<flags>] <query>
     Run a LogQL query.
 
-    The "query" command is useful for querying for log lines. The default output
-    of this command are log entries (a combination of timestamp, labels, and a
-    log line) along with various extra information about the performed query and
-    its results. Raw log lines (i.e., without a label and timestamp) can be
-    retrieved by passing the "-o raw" flag. The extra information about the
-    query (API URL, set of common labels, excluded labels) can be suppressed
-    with the --query flag.
+    The "query" command is useful for querying for logs. Logs can be returned in
+    a few output modes:
+
+      raw: log line
+      default: log timestamp + log labels + log line
+      jsonl: JSON response from Loki API of log line
+
+    The output of the log can be specified with the "-o" flag, for example, "-o
+    raw" for the raw output format.
+
+    The "query" command will output extra information about the query and its
+    results, such as the API URL, set of common labels, and set of excluded
+    labels. This extra information can be suppressed with the --quiet flag.
 
     While "query" does support metrics queries, its output contains multiple
     data points between the start and end query time. This output is used to
@@ -129,6 +137,11 @@ Commands:
     This command does not produce useful output when querying for log lines; you
     should always use the "query" command when you are running log queries.
 
+    For more information about log queries and metric queries, refer to the
+    LogQL documentation:
+
+    https://github.com/grafana/loki/blob/master/docs/logql.md
+
   labels [<label>]
     Find values for a given label.
 
@@ -137,12 +150,19 @@ usage: logcli query [<flags>] <query>
 
 Run a LogQL query.
 
-The "query" command is useful for querying for log lines. The default output of
-this command are log entries (a combination of timestamp, labels, and a log
-line) along with various extra information about the performed query and its
-results. Raw log lines (i.e., without a label and timestamp) can be retrieved by
-passing the "-o raw" flag. The extra information about the query (API URL, set
-of common labels, excluded labels) can be suppressed with the --query flag.
+The "query" command is useful for querying for logs. Logs can be returned in a
+few output modes:
+
+  raw: log line
+  default: log timestamp + log labels + log line
+  jsonl: JSON response from Loki API of log line
+
+The output of the log can be specified with the "-o" flag, for example, "-o raw"
+for the raw output format.
+
+The "query" command will output extra information about the query and its
+results, such as the API URL, set of common labels, and set of excluded labels.
+This extra information can be suppressed with the --quiet flag.
 
 While "query" does support metrics queries, its output contains multiple data
 points between the start and end query time. This output is used to build
@@ -175,7 +195,9 @@ Flags:
                          LOKI_CLIENT_CERT_PATH env var.
       --key=""           Path to the client certificate key. Can also be set
                          using LOKI_CLIENT_KEY_PATH env var.
-      --org-id=ORG-ID    org ID header to be substituted for auth
+      --org-id=ORG-ID    adds X-Scope-OrgID to API requests for representing
+                         tenant ID. Useful for requesting tenant data when
+                         bypassing an auth gateway.
       --limit=30         Limit on number of entries to print.
       --since=1h         Lookback window.
       --from=FROM        Start looking for logs at this absolute time
@@ -196,55 +218,4 @@ Flags:
 
 Args:
   <query>  eg '{foo="bar",baz=~".*blip"} |~ ".*error.*"'
-
-$ logcli help instant-query
-usage: logcli instant-query [<flags>] <query>
-
-Run an instant LogQL query.
-
-The "instant-query" command is useful for evaluating a metric query for a single
-point in time. This is equivalent to the Grafana Explore table view; if you want
-a metrics query that is used to build a Grafana graph, you should use the
-"query" command instead.
-
-This command does not produce useful output when querying for log lines; you
-should always use the "query" command when you are running log queries.
-
-Flags:
-      --help             Show context-sensitive help (also try --help-long and
-                         --help-man).
-      --version          Show application version.
-  -q, --quiet            suppress query metadata
-      --stats            show query statistics
-  -o, --output=default   specify output mode [default, raw, jsonl]. raw
-                         suppresses log labels and timestamp.
-  -z, --timezone=Local   Specify the timezone to use when formatting output
-                         timestamps [Local, UTC]
-      --addr="http://localhost:3100"
-                         Server address. Can also be set using LOKI_ADDR env
-                         var.
-      --username=""      Username for HTTP basic auth. Can also be set using
-                         LOKI_USERNAME env var.
-      --password=""      Password for HTTP basic auth. Can also be set using
-                         LOKI_PASSWORD env var.
-      --ca-cert=""       Path to the server Certificate Authority. Can also be
-                         set using LOKI_CA_CERT_PATH env var.
-      --tls-skip-verify  Server certificate TLS skip verify.
-      --cert=""          Path to the client certificate. Can also be set using
-                         LOKI_CLIENT_CERT_PATH env var.
-      --key=""           Path to the client certificate key. Can also be set
-                         using LOKI_CLIENT_KEY_PATH env var.
-      --org-id=ORG-ID    org ID header to be substituted for auth
-      --limit=30         Limit on number of entries to print.
-      --now=NOW          Time at which to execute the instant query.
-      --forward          Scan forwards through logs.
-      --no-labels        Do not print any labels
-      --exclude-label=EXCLUDE-LABEL ...
-                         Exclude labels given the provided key during output.
-      --include-label=INCLUDE-LABEL ...
-                         Include labels given the provided key during output.
-      --labels-length=0  Set a fixed padding to labels
-
-Args:
-  <query>  eg 'rate({foo="bar"} |~ ".*error.*" [5m])'
 ```