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.


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.


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.


# 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.


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.


# 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


# 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.