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-scraperBy 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). Never reaches past your plan’s retention | |
--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 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] messageFor 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 connectionIn 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 scrapeHow 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
}| Field | Value |
|---|---|
logs | The lines, newest first, as in the text output |
retention_days | Your plan’s retention in days; null where it is negotiated |
since_clamped | true 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 --followThree 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. |
--json streams | With --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,stderrThe 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-7c2e9b5d3a18This 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 --jsonNote 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.