description: Installation and reference for LogCLI, a command-line tool for querying and exploring logs in Grafana Loki.
aliases:
- ../getting-started/logcli/
- ../tools/logcli/
- ../query
- ../query/logcli/
weight: 150
---
# LogCLI getting started
LogCLI is the command-line interface to Grafana Loki.
It facilitates running [LogQL](https://grafana.com/docs/loki/<LOKI_VERSION>/query)
queries against a Loki instance.
logcli is a command-line client for Loki that lets you run [LogQL](https://grafana.com/docs/loki/<LOKI_VERSION>/query) queries against your Loki instance. 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.
## Installation
This is useful, for example, if you want to download a range of logs from Loki. Or want to perform analytical administration tasks, for example, discover the number of log streams to understand your label cardinality, or find out the estimated volume of data that a query will search over. You can also use logcli as part of shell scripts.
If you are a Grafana Cloud user, you can also use logcli to query logs that you have exported to long-term storage with [Cloud Logs Export](https://grafana.com/docs/grafana-cloud/send-data/logs/export/), or any other Loki formatted log data.
{{<admonitiontype="note">}}
Note that logcli is a querying tool, it cannot be used to ingest logs.
{{</admonition>}}
## Install logcli
As a best practice, you should download the version of logcli that matches your Loki version. And upgrade your logcli when you upgrade your version of Loki.
`<command>` points to one of the commands, detailed in the [command reference](http://localhost:3002/docs/loki/<LOKI_VERSION>/query/logcli/getting-started/#logcli-command-reference) below.
Otherwise you can point LogCLI to a local instance directly
without needing a username and password:
`<flags>` is one of the subcommands available for each command.
```bash
export LOKI_ADDR=http://localhost:3100
```
`<args>` is a list of space separated arguments. Arguments can optionally be overridden using environment variables. Environment variables will always take precedence over command line arguments.
{{<admonitiontype="note">}}
If you are running Loki behind a proxy server and you have
authentication configured, you will also have to pass in LOKI_USERNAME
and LOKI_PASSWORD, LOKI_BEARER_TOKEN or LOKI_BEARER_TOKEN_FILE accordingly.
You can use the logcli `–stdin` argument to run a command against a log file on your local machine, instead of a Loki instance. This lets you use LogQL to query a local log file without having to load the file into Loki, for example if you have downloaded a log file and want to query it outside of Loki.
If you have log files in your local machine, and just want to run some LogQL queries against those log files, `--stdin` flag can help.
You may use `stdin` flag to do the following:
You can consume log lines from your `stdin` instead of Loki servers.
- Use as a quick way to test or validate a LogQL expression against some log data.
- Learn the basics of LogQL with just local log files and the `logcli` tool (without needing to set up Loki servers, Grafana, etc.).
- Enable troubleshooting by letting you run queries without accessing a Loki instance.
- Use LogQL to parse and extract data from a local log file without ingesting the data into Loki.
- Enable discussion on public forums, for example submitting questions and answers, and sharing LogQL expressions.
Say you have log files in your local, and just want to do run some LogQL queries for that, `--stdin` flag can help.
#### Notes on `stdin` usage
1. The `--limits` flag doesn't have any meaning when using `--stdin` (use pager like `less` for that).
1. Be aware there are no **labels** when using `--stdin`. So the stream selector in the query is optional, for example, just `|="timeout"|logfmt|level="error"` is same as `{foo="bar"}|="timeout|logfmt|level="error"`.
{{<admonitiontype="note">}}
Currently it doesn't support any type of metric queries.
Currently `stdin` doesn't support any type of metric queries.
{{</admonition>}}
You may have to use `stdin` flag for several reasons
1. Quick way to check and validate a LogQL expressions.
2. Learn basics of LogQL with just Log files and `LogCLI`tool ( without needing set up Loki servers, Grafana etc.)
3. Easy discussion on public forums. Like Q&A, Share the LogQL expressions.
**NOTES on Usage**
1. `--limits` flag doesn't have any meaning when using `--stdin` (use pager like `less` for that)
1. Be aware there are no **labels** when using `--stdin`
- So stream selector in the query is optional e.g just `|="timeout"|logfmt|level="error"` is same as `{foo="bar"}|="timeout|logfmt|level="error"`
**Examples**
1. Line filter - `cat mylog.log | logcli --stdin query '|="too many open connections"'`
logcli sends queries to Loki in such a way that query results arrive in batches.
The `--limit` option for a `logcli query` command limits the total number of log lines that will be returned for a single query.
When not set, `--limit` defaults to 30.
The limit protects the user from overwhelming Loki in cases where the specified query would have returned a large number of log lines.
The limit also protects the user from unexpectedly large responses.
Larger result sets can be batched for easier consumption. Use the `--batch` option to control the number of log line results that are returned in each batch.
When not set, `--batch` defaults to 1000.
Setting a `--limit` value larger than the `--batch` value will cause the
requests from logcli to Loki to be batched.
When you run a query in Loki, it will return up to a certain number of log lines. By default, this limit is 5000 lines. You can configure this server limit with the `limits_config.max_entries_limit_per_query` in Loki's configuration.
Batching lets you query for a results set that is larger than this server-side limit, as long as the `--batch` value is less than the server limit.
Query metadata is output to `stderr` for each batch.
To suppress the output of the query metadata, set the `--quiet` option on the `logcli query` command line.
Print all labels and their unique values. This command is especially useful for finding [high-cardinality labels](https://grafana.com/docs/loki/<LOKI_VERSION>/get-started/labels/#cardinality) in the index.
```bash
logcli series '{cluster="vinson"}' --analyze-labels
J Stickler
1 year ago
committed by