This article follows the official documentation. We haven’t tested this tool for a hands-on review.
When a coding agent needs evidence from service logs, it can use Grafana LogCLI to query Grafana Loki from a shell. Loki is Grafana’s log storage and search system. It groups log streams by labels such as service or environment, then searches the log lines selected by those labels.
LogCLI sends LogQL queries, Loki’s language for selecting and filtering logs, to a Loki instance. A query limited by time range and result count returns a structured set of results for the agent to inspect in JSON Lines format. The commands below make network requests to Loki and read logs; they do not change Loki or ingest new logs. See the LogCLI documentation and Loki repository overview for the tool’s role in the Loki stack.
Install the matching LogCLI version
Grafana recommends matching LogCLI's version to the Loki version you query, and upgrading LogCLI when you upgrade Loki. Download the appropriate operating-system binary using the LogCLI documentation, then place it somewhere on your PATH so the shell can find the logcli command. Grafana also documents building LogCLI from source in its getting-started instructions.
The commands in the example assume LogCLI is installed and available in the shell. The URL and label values are placeholders: replace them with the Loki endpoint and labels for your own data.
Configure access to Loki
LogCLI needs the address of a Loki instance. Set LOKI_ADDR to that endpoint; the documentation also supports the --addr command-line option. For an endpoint that requires basic authentication, configure LOKI_USERNAME and LOKI_PASSWORD, or use the corresponding --username and --password options. Set LOKI_ORG_ID or use --org-id when your Loki setup requires a tenant ID. Grafana lists these settings in its LogCLI authentication documentation.
export LOKI_ADDR='https://<your-loki-endpoint>'
export LOKI_USERNAME='<your-username>'
export LOKI_PASSWORD='<your-password>'
export LOKI_ORG_ID='<your-tenant-id>'
Use only the variables your endpoint requires. These values are placeholders, not credentials. Keep real credentials in the shell environment or an approved secret store; do not paste them into an agent prompt. LogCLI gives environment variables precedence over command-line arguments, so check for inherited LOKI_* values when a command unexpectedly targets the wrong endpoint or tenant.
Run a bounded query
For example, ask LogCLI to find error lines from one labeled stream within a selected time range:
logcli query \
--since="$TIME_RANGE" \
--limit="$ENTRY_LIMIT" \
--output=jsonl \
'{job="varlogs"} |= "error"'
The selector {job="varlogs"} chooses streams with that label and value. The |= "error" filter keeps lines containing the text error. Replace the selector with labels that exist in your Loki data; the example does not assume that your instance has a varlogs stream. Set TIME_RANGE and ENTRY_LIMIT to values appropriate for your query. --since="$TIME_RANGE" bounds the time range, while --limit="$ENTRY_LIMIT" caps the returned log entries. --output=jsonl requests JSON Lines, a format that puts one JSON record on each line and is convenient for shell tools and agents to parse.
The command sends a read query to the configured Loki endpoint. LogCLI reports details about the query, which can include the API URL and common or excluded labels, along with the results. An agent should distinguish that query information from the returned log records rather than treating every line of output as an application log. For more query and output options, use the official LogCLI command reference.
Give an agent a focused task
Ask the agent to inspect recent errors after a code change and report repeated messages without changing files. For example:
Query Loki for error log entries from the service label I specify, using a time range and result limit I specify. Use JSON Lines output. Summarize repeated error messages and their timestamps, and do not change any files. Do not reproduce credentials or unrelated log content.
The agent still needs the correct endpoint, tenant, and label values in its shell environment. Log records can contain sensitive data, so limit the query to the relevant service and time range, and ask the agent to summarize rather than copy entire records into its response.
LogCLI queries and explores logs, but it does not ingest them. It cannot replace a log collector such as Grafana Alloy. A coding agent can use LogCLI to retrieve a limited slice of existing Loki data and use it to guide debugging. Read more in the LogCLI documentation, or return to the CLI directory.