Skip to Content
CLIafy logs
Raw

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

FlagShortTypeDefaultDescription
--tail-nint50Number of lines to show
--follow-fboolfalseFollow log output (stream)
--sincestringemptyShow logs since duration (e.g., 1h, 30m). Never reaches past your plan’s retention
--levelstringemptyFilter by level(s), comma-separated (e.g. ERROR,WARN)
--streamstringemptyFilter by stream(s), comma-separated (stdout,stderr,system)
--runstringemptyScope logs to a single run ID (from ‘afy 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

How far back Aetherfy logs go

afy logs shows only what your plan keeps: 3 days and 50 MB per account on Free, 14 days and 250 MB on Starter, 30 days and 1 GB on Performance, negotiated on Enterprise. Whichever limit is reached first applies. The size counts each line’s message bytes, at least 64 for a short line, across all your agents. When an account is over its size the oldest lines are removed first, and because the cleanup runs hourly an account may run over its size for up to an hour. See runs and logs.

A --since that reaches further back than your plan’s retention is not an error. The logs that are kept are shown, and a note goes to stderr, so a script reading stdout is not disturbed:

Note: --since 30d reaches past your plan's log retention (3 days); showing what is kept.

When the size limit has removed lines your retention would still have kept, a second note says so and gives the time before which nothing is left. A request the control plane cannot answer, including a response that does not state your plan’s retention, fails with a non-zero exit and an Error: line like every other command; with --json the error is the document described on the CLI overview.

With --json, afy logs prints one object, even when no line matches:

{ "logs": [], "retention_days": 3, "since_clamped": false }
FieldValue
logsThe lines, newest first, as in the text output
retention_daysYour plan’s retention in days; null where it is negotiated
since_clampedtrue when --since reached past the retention and was cut to it

--follow --json is not this object: it prints one compact JSON object per line.

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.

The first read, which places the stream at the newest line, is a read like every poll after it. If the control plane refuses it (an agent that does not exist, a key that may not read it) the command ends with an Error: line and a non-zero exit. If the control plane is briefly unavailable, or the network fails, afy logs --follow says so once (Failed to start following logs: ... (still trying)) and keeps trying every 2 seconds, so a follow started in the middle of a deploy waits instead of failing. The same applies to a poll after the stream has started: an outage is said once and followed on past; a refusal ends the command.

afy logs catalogue-scraper --follow

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

CaveatDetail
--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.
--json streamsWith --json, follow mode prints one compact JSON object per line, not text.

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. It also shows what the vector database refused the agent’s key and what the agent deleted from it: afy logs my-agent --stream system --json returns them with stream system and level SYSTEM. The lines are listed in runs and logs.

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 runs <agent>, and afy run prints the ID of the run it just started.

# Find the run afy runs catalogue-scraper # Read just that run afy logs catalogue-scraper --run 9f3a1c72-5b8e-4d61-a0f4-7c2e9b5d3a18

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 9f3a1c72-5b8e-4d61-a0f4-7c2e9b5d3a18 --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.

Last updated on