> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read and follow logs

> List streams, print and follow the logs of a stream with a field query or an SQL condition, read the logs around a moment, run SQL, and see the fields of a stream with the MoleSignal CLI.

## List the streams

```bash theme={null}
molesignal streams
```

The list shows each logs stream the user can read, with its number of fields, its retention, and
its description. `--type` lists the streams of another kind: `metrics`, `traces`, `profiles`, or
`extend`. `--names` prints only the names, and `--json` prints one stream per line as JSON.

## Print the newest logs

```bash theme={null}
molesignal logs app_logs
```

The command prints the newest 100 logs of the last 15 minutes, oldest first, one per line: the
time, the level, the service, and the message.

```text theme={null}
2026-10-18 03:14:15.361 INFO  checkout order 4812 created
2026-10-18 03:14:25.361 ERROR payment gateway timeout after 3 retries
```

The level is read from a field such as `level`, `severity`, or `severity_text`, the service from
`service` or `service.name`, and the message from `message`, `msg`, `body`, or `log`. A log
without a message field shows its other fields as `name=value`. Colours appear on a terminal;
`NO_COLOR` turns them off and `FORCE_COLOR` keeps them in a pipe.

| Option | Default | Meaning |
| - | - | - |
| `-n`, `--lines <count>` | `100` | How many of the newest logs to print first, at most `5000`. |
| `--since <duration>` | `15m` | How far back to look: `30s`, `10m`, `2h`, `1d`, `1w`. |
| `--from <time>`, `--to <time>` | none | A window instead of `--since`: an ISO time, `2026-10-26 14:00` in local time, or a duration back from now such as `2h`. |
| `-q`, `--query <query>` | none | A field query, as the **Logs** page takes it. |
| `--where <condition>` | none | An SQL condition on the fields of the stream. |
| `--fields <a,b,c>` | all | Prints the time and only these fields, as `name=value`. |
| `--json` | off | Prints each log as one line of JSON. |
| `--utc` | off | Prints times in UTC instead of local time. |
| `--web` | off | Opens the same logs on the **Logs** page instead of printing them. |

## Filter logs

`-q` takes a field query, the language of the **Logs** page: comparisons such as
`level = 'error'`, `contains`, `MATCH`, and `MATCH_TEXT`, joined with `AND` and `OR` and grouped
with brackets. Text without a field is searched for in `message`:

```bash theme={null}
molesignal logs app_logs --since 1h -q "level = 'error' AND (service = 'payment' OR timeout)"
```

`--where` takes an SQL condition on the stream's fields, as in the `WHERE` clause of a query:

```bash theme={null}
molesignal logs app_logs --where "status >= 500 AND duration_ms > 2000"
```

Given both, a log meets both. A condition that names a missing field, or that is not valid SQL,
ends the command with the reason.

## Follow new logs

```bash theme={null}
molesignal logs app_logs -f
```

After the newest logs, the command keeps printing the ones that arrive until **Ctrl+C**:

* It reads again every 2 seconds; `--interval` changes this.
* Each read starts 10 seconds before the end of the previous one, so that a log that reaches
  MoleSignal a few seconds late still appears. Each log appears once.
* A burst larger than one read is read on at once, without waiting.
* A lost connection is retried with a growing pause of up to 30 seconds. The CLI reports the loss
  and the return on standard error.

A follow tracks time in the logs themselves. A log that arrives with a time older than the start
of the current read does not appear. `--to` does not go with `-f`.

## Read the logs around a moment

`--around` prints the logs just before and just after a moment, with a line at the moment
between them. `-B` and `-A` set how many, 10 each by default and 250 at most. `-q` and `--where`
narrow them:

```bash theme={null}
molesignal logs app_logs --around "2026-10-26 14:03:12.345" -B 20 -A 20
```

A time copied from the output of `molesignal logs` is a moment `--around` takes.

## Run SQL over a stream

`molesignal query` runs one read-only SQL statement, with expressions, joins, and aggregates, and
prints the result as a table:

```bash theme={null}
molesignal query "SELECT level, COUNT(*) AS logs FROM app_logs GROUP BY level ORDER BY logs DESC"
```

The stream is the first one after `FROM`; `--stream` names another. The window is the last hour by
default; `--since`, `--from`, and `--to` change it. `-n` sets the most rows, `1000` by default and
`5000` at most. `--csv` prints CSV with a head line, `--json` one row per line as JSON, and
`--web` opens the statement on the **Logs** page.

## See the fields of a stream

```bash theme={null}
molesignal fields app_logs
```

The list shows each field with its type and its index. Given a field, the command lists its most
common values over the last hour, with their counts:

```bash theme={null}
molesignal fields app_logs service --since 1d
```

`--match` keeps the values that contain a text, and `-n` sets how many, `20` by default.
`--type` reads a stream of another kind.

## Use the output in a pipe

`--json` prints each log with all its fields:

```bash theme={null}
molesignal logs app_logs -n 1000 --since 2h --json | jq -r .message
```

A reader that stops early, such as `head`, ends the command quietly.

## Access

The CLI reads with MoleSignal's tools `list_streams`, `query_logs`, `get_stream_schema`,
`search_field_values`, and `search_around`, with the permissions of the signed-in user or of the
owner of the API token. The user needs `streams.query`, and the organization's Tool Policy must
not switch these tools off.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.