---
slug: cli/logs
title: afy logs — Aetherfy agent log reference
kind: reference
surface: cli
summary: Reference for afy logs in the Aetherfy CLI — every flag including --tail, --follow, --since, --level, --stream and --run, the output line format, the server-side 1000-line cap, and the flags that --follow ignores.
sources:
  - aetherfy-cli:cmd/logs.go
  - aetherfy-cli:internal/api/logs_query_test.go
---

# afy logs

## Reading Aetherfy agent logs

`afy logs <agent>` fetches log lines for an Aetherfy agent. It takes exactly one
required positional argument, the agent name.

```bash
afy logs catalogue-scraper
```

By default it prints the 50 most recent lines and exits. Log output covers both
long-running service agents and individual runs of task agents; a single run can
be isolated with `--run`.

## Flags accepted by afy logs in the Aetherfy CLI

| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
| `--tail` | `-n` | int | 50 | Number of lines to show |
| `--follow` | `-f` | bool | false | Follow log output (stream) |
| `--since` | | string | empty | Show logs since duration (e.g., 1h, 30m) |
| `--level` | | string | empty | Filter by level(s), comma-separated (e.g. ERROR,WARN) |
| `--stream` | | string | empty | Filter by stream(s), comma-separated (stdout,stderr,system) |
| `--run` | | string | empty | Scope logs to a single run ID (from 'afy agents runs') |

The Aetherfy server caps `--tail` at 1000 lines. Asking for more returns 1000.

## The Aetherfy log line format

In non-follow mode each line is printed as:

```
YYYY-MM-DD HH:MM:SS [LEVEL] message
```

For example:

```
2026-08-15 03:00:12 [INFO] starting catalogue scrape
2026-08-15 03:00:19 [WARN] retrying page 4 after 502
2026-08-15 03:01:44 [ERROR] upstream refused connection
```

In follow mode the Aetherfy CLI shortens the timestamp to `HH:MM:SS`, since the
date is implied by the live stream:

```
03:00:12 [INFO] starting catalogue scrape
```

## Following an Aetherfy log stream

`--follow` (`-f`) streams new log lines as they arrive. The Aetherfy CLI polls
every 2 seconds. Stop the stream with Ctrl+C.

```bash
afy logs catalogue-scraper --follow
```

Three caveats apply to follow mode and are easy to trip over:

| Caveat | Detail |
|---|---|
| `--tail` is ignored | `--follow` does not honour the line count; it starts from the current tail of the Aetherfy stream. |
| `--since` is ignored | `--follow` does not honour the time window either. |
| `-o json` is ignored | Follow mode always prints text, regardless of the global output format flag. |

To get a bounded historical window, run `afy logs` without `--follow`.

## Filtering Aetherfy logs by level and stream

`--level` takes one or more log levels, comma-separated. `--stream` takes one or
more of `stdout`, `stderr`, and `system`, comma-separated.

```bash
# Errors and warnings only
afy logs catalogue-scraper --level ERROR,WARN

# Only what the process wrote to stderr
afy logs catalogue-scraper --stream stderr

# Both filters together
afy logs catalogue-scraper --level ERROR --stream stdout,stderr
```

The `system` stream carries the Aetherfy platform's own messages about the agent
(start, stop, and lifecycle events) rather than anything the agent code printed.

## Scoping Aetherfy logs to a time window

`--since` takes a duration such as `1h` or `30m` and limits the results to lines
newer than that.

```bash
afy logs catalogue-scraper --since 1h
afy logs catalogue-scraper --since 30m --tail 200
```

`--since` is honoured only in non-follow mode; see the follow-mode caveats above
on this page.

## Reading the logs of a single Aetherfy run

`--run` scopes the output to one run of a task agent. Run IDs come from
`afy agents runs <agent>`, and `afy agents run` prints the ID of the run it just
started.

```bash
# Find the run
afy agents runs catalogue-scraper

# Read just that run
afy logs catalogue-scraper --run run_01J8ZQ4T7M2C9V
```

This is the standard way to inspect one execution of an Aetherfy scheduled task
without wading through every other execution.

## Worked afy logs examples for Aetherfy agents

```bash
# The default: 50 most recent lines
afy logs catalogue-scraper

# The last 100 lines
afy logs catalogue-scraper --tail 100

# Live stream, stopped with Ctrl+C
afy logs catalogue-scraper --follow

# Errors and warnings only
afy logs catalogue-scraper --level ERROR,WARN

# Everything on stderr in the last hour
afy logs catalogue-scraper --stream stderr --since 1h

# A single run, as JSON
afy logs catalogue-scraper --run run_01J8ZQ4T7M2C9V -o json
```

Note that `afy logs` prints an `Error:` line and still exits 0 on failure, so a
script must inspect the output rather than the exit status. The full exit-code
table for the Aetherfy CLI is on [/cli](/cli).