Aetherfy agent commands
Agents are the default noun in the Aetherfy CLI
A bare verb is an agent verb. afy list lists your Aetherfy agents, afy status <name> describes one, and afy stop <name> pauses one. Only the other kinds of
object keep a group of their own: afy secrets, afy workspaces, afy github,
and the vector groups afy collections, afy index and afy points.
Each of these commands is spelled exactly one way. There is no afy agents
group and no alias for one.
| Subcommand | Purpose |
|---|---|
afy list | List every agent in the account |
afy create <name> | Create an agent in a workspace |
afy delete <name> | Delete an agent permanently |
afy stop <name> | Pause an agent |
afy start <name> | Resume a paused agent |
afy archive <name> | Free the plan quota slot, keeping configuration and code |
afy restore <name> | Re-provision an archived agent |
afy cancel <name> | Cancel a pending deployment |
afy status <name> | Show detailed agent status |
afy update <name> | Rename an agent, move it to another workspace, or set its description |
afy access <name> | Show or change the workspaces the agent’s key can use |
afy diff | Compare local aetherfy.yaml against the linked agent’s live configuration |
afy run <name> | Run an agent once, immediately |
afy runs <name> | Show run history |
afy schedule pause <name> | Pause the agent’s scheduled task |
afy schedule resume <name> | Resume the agent’s scheduled task |
Two things do not exist in the Aetherfy CLI and are commonly assumed:
- There is no
afy schedule set. A schedule is declared with theschedule:key inaetherfy.yamland applied byafy deploy. See /agents/scheduled-tasks. - There is no
afy pauseorafy resume. The pause and resume verbs for an agent areafy stopandafy start. afy renameandafy pullare gone. Renaming isafy update <name> --name; exporting an agent’s configuration isafy init --agent <name>, which writes it asaetherfy.yamlin the folder it links (deploy).
Listing Aetherfy agents
afy list prints every agent in the account. It takes no arguments and
no flags of its own.
afy list
afy list --jsonThe default columns are:
| Column | Meaning |
|---|---|
| Name | The agent name |
| Type | SERVICE or JOB |
| Status | Current lifecycle status |
| Regions | The regions the agent is deployed in |
| ID | The Aetherfy agent ID |
When at least one agent in the account has a scheduled task, the table grows to eight columns: Name, Type, Status, Regions, Schedule, Next Run, Last Run, ID.
| Column | Rendering |
|---|---|
| Schedule | The declared schedule expression |
| Next Run | A UTC timestamp, or (paused) when the schedule is paused |
| Last Run | The most recent run’s outcome and how long ago it started, such as failed, 2m ago, or never. When the schedule’s last tick did not start a run, a second line says so: tick skipped (5m ago) or tick missed (5m ago). A tick that fired adds nothing — its run is the first line. The reason a run failed is printed by afy status |
A status of usage_paused renders as paused (usage limit) — the agent was
paused by the Aetherfy usage meter, not by afy stop. On a paid plan that means a spend limit was reached; on Free, which has no spend limit, the agent was awake beyond 75% of the month and it resumes within a day of the new month starting (UTC).
Creating an Aetherfy agent
afy create <name> creates an agent, with no code yet, in a workspace. It takes
exactly one positional argument, the name.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--description | -d | string | empty | Agent description |
--workspace | string | empty | The workspace the agent lives in (asked when the account has several) |
The agent lives in the workspace --workspace names. With one workspace in the
account, that one is used; with several you are asked, and without a terminal
--workspace is required. An empty --workspace "" is refused: everything lives
in a named workspace. No environment variable sets it.
# In the account's only workspace
afy create invoice-parser
# In a named workspace, with a description
afy create invoice-parser --workspace acme -d "Parses inbound invoices"How the agent runs (its runtime, type, memory, regions and the rest) comes from
aetherfy.yaml at its first deploy, so afy create takes no --type or
--runtime. To work on it from a folder, link the folder with
afy init --agent invoice-parser, then afy deploy. afy init with no --agent
creates an agent and links the folder in one step: see
/cli/deploy.
Deleting an Aetherfy agent
afy delete <name> permanently deletes the agent.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--yes | -y | bool | false | Delete without asking |
Without --yes the Aetherfy CLI asks you to type the agent name exactly before
it proceeds. Typing anything else, or answering with an empty line, cancels: the
command exits 1 with Cancelled, deletes nothing, and under --json writes an
error document (code CLI_CANCELLED) on stderr and nothing on stdout. A cancelled delete never exits 0,
so a script cannot take it for a delete that happened. Without a terminal (a
script, a pipe) the question cannot be answered, so the command is refused before
asking, with exit 2: This deletes agent '<name>' and all its deployments; pass --yes to confirm without a prompt.
afy delete scraper
afy delete scraper --yesIf your goal is to free a plan quota slot rather than lose the agent, use
afy archive instead — it preserves the configuration and the stored code
bundle.
Pausing and resuming an Aetherfy agent with stop and start
afy stop <name> pauses an Aetherfy agent. It stops every machine and
prevents the proxy from re-waking the agent on incoming traffic. The pause is
reversible.
afy start <name> resumes an agent that was paused with stop.
afy stop api-gateway
afy start api-gatewayFor a service agent, afy start returns once every machine has booted and
waits, up to a bound, for your code to answer its health check, and says what it
found. A job agent is resumed without starting a machine — its machines wake for
runs — so afy start says only that it resumed:
readiness | What afy start tells you |
|---|---|
serving | The agent resumed and is serving requests |
starting | The agent resumed; your code is still starting, and requests sent now are held until it is listening |
load_failed | The agent resumed, but your code failed to load, so its requests will fail — afy logs <name> has the error |
unconfirmed | The agent resumed and its machines started, but your code was not confirmed serving: it did not answer in the time allowed — afy logs <name> shows where it is — or you archived, deleted or paused the agent while afy start was answering, and its machines were being stopped |
slow_start | The agent resumed, but starting its machines took longer than it should, so your code was not checked — the delay was on Aetherfy’s side |
null | A job agent, which serves no requests: it says only that the agent resumed |
The agent is resumed in every case, and the command exits 0 — these describe your code, not the resume. The same field is in the API response, described in Stopping and starting.
When a machine’s host has no room to resume it, the start is accepted too: afy start
says the agent is being started on a new machine, how long that can take at most, and
exits 0. With --wait it follows the agent as below, and once the agent is running it
says it was a cold start — a new machine from the agent’s current release, not a resume
of the old one. The details are in
Starting when a machine’s host is full.
Run afy start right after afy stop and the stop may still be finishing — your
server gets its shutdown grace. The start is then accepted, not refused: the command
says the agent will start once its previous stop finishes, how long that can take at
most, and exits 0. Aetherfy starts the agent itself when the stop completes, so there is
nothing to re-run, and interrupting the command loses nothing. afy status <name> shows
the pending start until the agent is running, or why it was dropped. With --wait,
afy start follows the agent until it is running — for as long as the server says the
start can take — and exits 1 with the reason if the start was dropped (an afy stop, an
archive or a delete, a billing hold, or a stop or start that failed), so a script can go
on to send the agent requests. If that time passes with the start still pending, it
says Aetherfy is still retrying and that afy status <name> shows the result, and exits
4: the start has not failed, and Aetherfy carries it out on its own. The details are in
Starting while the previous stop is still finishing.
A start is accepted the same way, with no stop involved, when starting the machines
takes too long. If the machines have not finished starting after 90
seconds, Aetherfy stops waiting on it in that request and finishes the start itself:
afy start says the machines had not finished starting and that Aetherfy finishes the start, with
the server’s bound (at most 159 seconds), and exits 0. afy status <name> shows the
start as starting (the machines were slow to start) until the
agent is running. Nothing is re-sent, and interrupting the command loses nothing;
--wait follows it exactly as it follows a start accepted during a stop.
Waiting for an Aetherfy agent to start with —wait
--wait matters only when the start is accepted rather than carried out at once; a
start that boots the agent straight away answers as in the table above, with or
without it. A script that has to send the agent requests next stops it, starts it
with --wait, and branches on the exit code:
afy stop api-gateway
afy start api-gateway --wait
case $? in
0) echo "running" ;;
4) echo "still being started by Aetherfy" ;;
*) echo "not started" ;;
esacA start accepted while the stop was still finishing, carried out within the bound
(exit 0). The bound is the server’s own wait_bound_seconds for this start, so the
number you see differs:
✓ Agent 'api-gateway' will start once its previous stop finishes (at most 279s).
✓ Agent 'api-gateway' resumed.A start on a full host, carried out on a new machine (exit 0):
✓ Agent 'api-gateway' is being started on a new machine: its machine's host has no room to resume it, so Aetherfy recreates it from the current release (at most 413s).
✓ Agent 'api-gateway' resumed.
Its machine's host had no room to resume it, so it was started on a new machine from its current release: a cold start.A start handed over because the machines were slow to start (exit 0):
✓ Agent 'api-gateway' is being started by Aetherfy: the machines had not finished starting when the request gave up, so Aetherfy finishes the start (at most 159s).
✓ Agent 'api-gateway' resumed.A start still pending when the bound has passed (exit 4). The agent is read every 5 seconds, so the time it names is the bound rounded up to the next read:
✓ Agent 'api-gateway' will start once its previous stop finishes (at most 279s).
Warning: Agent 'api-gateway' has not started within 280s. Aetherfy is still retrying the start; 'afy status api-gateway' shows the result.
Error: agent 'api-gateway' has not started within 280s; Aetherfy is still retryingA start that was dropped exits 1, with the reason, as described above.
afy stop takes no flags; afy start takes only --wait. A stopped Aetherfy agent
still bills at the base rate — stopping suspends execution, not billing. To stop billing
for an agent you are not using, archive it.
Archiving and restoring an Aetherfy agent
afy archive <name> destroys the underlying application to free the plan
quota slot while preserving the agent’s configuration and its stored code bundle.
It is reversible.
afy restore <name> re-provisions an archived Aetherfy agent from the
preserved bundle.
afy archive old-worker
afy restore old-workerRestoring consumes a plan quota slot, and the quota is re-checked at restore time. If you are already at your plan limit the restore is rejected until you free a slot or upgrade. Plan quotas are documented at /platform/limits.
afy restore returns once the restore is accepted. It is checked again when it
runs, and a restore refused then leaves the agent archived: afy status <name>
prints a Reason line saying why and what to do. afy list shows the status
alone, which reads the same for a restore still running and a refused one.
Cancelling a pending Aetherfy deployment
afy cancel <name> cancels a pending deployment for the agent. It takes
no flags.
afy cancel scraperOnly deployments in the QUEUED state are cancellable. A deployment whose build is
already in flight returns HTTP 409 from the Aetherfy API and cannot be cancelled;
wait for it to finish, then roll back with afy rollback if the result is wrong.
Inspecting an Aetherfy agent with status
afy status <name> prints the detailed state of a single Aetherfy agent.
It takes no flags of its own and honours --json.
afy status scraper
afy status scraper --jsonThe text output covers:
| Field | Notes |
|---|---|
| ID | The Aetherfy agent ID |
| Name | The agent name |
| Type | SERVICE or JOB |
| Status | Current lifecycle status, with health or degraded detail when present |
| Reason | Why the agent is not serving, when Aetherfy recorded a reason: its app or its image is no longer on the compute plane, every running machine of it is failing its health check (with the error the machine reports), or the compute plane no longer runs any of its machines. Absent otherwise |
| Warning | One line for each thing the Aetherfy control plane says to know about the agent, in its own words. Today that is its runtime having passed its end of life, with the day deploys on it stop and the runtime to create a new agent on. Absent when there is nothing to know. With --json they are the warnings array |
| Regions | The regions the agent is deployed in |
| Spawn Enabled | Whether this agent may start child agents |
| Workspace | The workspace the agent lives in |
| Schedule | The schedule expression, labelled UTC |
| Next run | Next scheduled fire time, or (paused) |
| Last tick | What the schedule last did when it did not start a run — skipped or missed — with the reason Aetherfy recorded. Absent when the last tick fired |
| Last run | The most recent run, whatever started it: its outcome, the reason when it failed, and how long ago it started, as in “failed (run exited with code 1), 2m ago”. never for a scheduled agent that has not run |
| Created | Creation timestamp |
| Updated | Last-modified timestamp |
| Description | The agent description |
| Spawn relationships | Parent and child agents |
| Last deploy, Deploy error | Only when the agent’s newest release deploy failed: v<N> failed, and the whole message of why. A push without aetherfy.yaml, or a frozen account’s refused deploy, is explained only here (the agent may still be serving its previous release) |
| Repo, Branch, Directory, Webhook id | The agent’s GitHub link, when it has one |
The GitHub link in status
An agent linked to a GitHub repository with
afy github link also gets its link printed: the repository, the
branch that is watched, the directory inside it — repository root when the
link has none — and the webhook id. An agent with no link prints none of this.
Three states leave that link intact and stop deploying anything, and afy status
is where the terminal can learn about each:
| What status says | What happened | What fixes it |
|---|---|---|
| GitHub disconnected — pushes are not deploying | The Aetherfy account is no longer connected to GitHub | afy github connect. The link is kept, so deploys resume on reconnect |
| Branch deleted — pushes are not deploying | The branch the link watches was deleted, and status names which and when | Recreate the branch and push. Relinking would succeed and change nothing |
Auto-deploy paused since <time> — pushes are not deploying | You paused auto-deploy on the link with afy github pause. The link is kept, and the warning can show beside either of the other two | afy github resume <agent>. afy deploy still deploys your code meanwhile |
The first two are not reported on GitHub. Aetherfy announces a skipped push as a check on the commit, which needs the installation token a disconnect removes, and a deleted branch has no commit to attach one to at all. A pause is announced on each commit it skips (pausing auto-deploy).
A push that arrived while a deploy of the agent was in progress waits for it, and has no deployment until it starts (pushing while a deploy is running). While one waits, status prints it:
Push waiting: 9f8e7d6, received 2026-09-26 12:00 UTC — deploys when the deploy in progress endsA push that Aetherfy is still cloning and checking has no deployment yet either. While one is being prepared, status prints it above the push waiting behind it:
Push preparing: 1a2b3c4, since 2026-11-14 10:15 UTC — becomes the next deployment when it is readyA tick that fired has started a run, and says nothing about how that run went:
the Last run line does. Read afy runs <name> for the runs before it.
afy status <name> --json carries the last run under a last_run key — id,
trigger_source, state, created_at, error_message and release_version —
and the link state under a github key, with
the API’s own field names — linked, repo, branch, root_dir,
webhook_id, account_connected, branch_deleted_at, auto_deploy_paused_at
(when auto-deploy was paused, or null when it is on), waiting_push
(sha and received_at, or null when no push waits) and push_in_clone
(id, sha and since, or null when no push is being prepared). The link is part of
the agent record afy status reads rather than a separate request, so a status
that printed has no second read that could have failed.
Updating an Aetherfy agent: its name, workspace or description
afy update <name> changes what the platform owns about an agent: its name, the
workspace it lives in, and its description. How the agent runs (runtime, memory,
regions and the rest) is aetherfy.yaml’s, and only a deploy changes that.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--name | string | empty | Rename the agent | |
--workspace | string | empty | Move the agent to this workspace (redeploys it) | |
--description | -d | string | empty | Set the agent’s description |
--yes | -y | bool | false | Move without asking (the list of what the move changes is still shown) |
At least one flag is required, and flags not given are left unchanged. An empty
--name or --workspace is refused. With nothing to change, or an empty value, the
command exits 2 before sending anything.
# Rename the agent
afy update my-agent --name invoice-parser
# Move it to another workspace (it is redeployed there)
afy update my-agent --workspace invoice-pipeline
# Set the description
afy update my-agent --description "Parses inbound invoices"A rename does not change the agent’s address, and the folders linked to it
keep deploying to it, because a link names the agent by id. Code that calls the
agent by its old name stops finding it. There is no file to rewrite: aetherfy.yaml
does not carry the name.
A move redeploys the agent, so its key reaches the new workspace at once (for a
task, from its next run). If it cannot be redeployed (the account is frozen, the release’s configuration is not on
record, the target workspace’s regions do not fit), the move is refused and says
why. Its conversation history stays in the old workspace. A move asks first and
lists what it changes (the sentences are on
Agent access):
the agent’s own level in the old workspace is cleared, its secrets switch is turned
off, a grant to the new home is dropped, and its other grants are kept, named with
their levels. The workspace it left does not become a grant, so it no longer
reaches it. --yes skips the question, not the list (stderr), and is required
without a terminal: without it the command exits 2 before changing anything. An
agent that already lives in the target workspace has nothing to confirm.
With both --name and --workspace, the move is done first, because it is the one
most likely to be refused, and a refused move then leaves everything as it was. If
the rename is refused after the move went through, the command says so: the agent
is in its new workspace under its old name.
Granting an Aetherfy agent another workspace with access
afy access <agent> shows, and changes, which workspaces an agent’s key can use on
the Aetherfy vector API, at which level, and whether its own key may write its own
secrets. The agent lives in one workspace and can access the ones you grant
it; any other workspace is refused to it. See
what an agent’s key reaches
and agent access for the three levels (read,
read_write, full).
# What can the agent reach?
afy access support-bot
# Grant it a second workspace; the command shows what becomes reachable and asks first
afy access support-bot --add research
# Let it write points there
afy access support-bot --add research --level read_write
# Only read where it lives; then back to the workspace's default
afy access support-bot --own-level read
afy access support-bot --own-level default
# Let its own key write its own secrets, then take that back
afy access support-bot --secrets on
afy access support-bot --secrets off
# From a script: grant one workspace, revoke another
afy access support-bot --add research --remove archive --yes --json| Flag | Default | Effect |
|---|---|---|
--add | — | Grant a workspace, by name. Repeat it, or give a comma-separated list |
--remove | — | Revoke a granted workspace, the same way |
--level | read for a new grant | The level of the --add workspaces: read, read_write or full. --add of a workspace already granted, with --level, changes its level. Without --add it is refused, exit 2 |
--own-level | — | The agent’s level where it lives: read, read_write, full, or default to follow the level its workspace sets for its agents (a workspace’s default is read_write) |
--secrets | — | on or off: whether the agent’s own key may create, update and delete its own secrets, never its workspace’s or another agent’s. A command of its own: refused, exit 2, beside --add, --remove, --level or --own-level |
--yes, -y | false | Change without asking |
--json | false | Print one JSON object: the agent’s resulting access, what was added and removed, and the levels changed (levels_changed, own_level_changed). Each workspace is there by name (own_workspace, granted_workspaces, allowed_workspaces) and as an {id, name} pair (own_workspace_ref, granted_workspace_refs, allowed_workspace_refs), for a script that keeps a reference |
A change that lets the agent’s code do more asks first: a grant, a higher level, a
higher --own-level, --secrets on. The command prints what would become possible
and asks Proceed? [y/N]. Answering no exits 1 with Cancelled: agent '<name>' was not changed and changes nothing. Without a terminal --yes is required: the
command exits 2 before asking and sends nothing otherwise (This grants access to agent '<name>'; pass --yes to confirm without a prompt.). With a terminal,
--json asks on stderr and keeps stdout to one object. A lower level,
--secrets off and removing narrow access and ask nothing, and a change that changes nothing says so
and asks nothing. The agent’s own workspace is not a grant: adding or removing it
is refused, exit 2, before anything is sent. So is an empty --add or --remove
value, and one starting with -, and a workspace both added and removed in one
command. Granting gives the agent access; it does not move it (moving is
afy update --workspace).
A change takes effect within 60 seconds (--secrets, on the agent’s next
request), and a grant and its level survive the agent’s redeploys. A secret the
agent writes is stored at once and read when the agent starts: a service sees it
after its next deployment, a task on its next run. Only your own key can change
access: an agent’s key is refused, and may only read its own.
Diffing local aetherfy.yaml against deployed Aetherfy state
afy diff compares the local aetherfy.yaml with the configuration of the agent
the folder is linked to (.aetherfy/agent.json), and prints what afy deploy
would change. It takes no positional arguments: the agent is the folder’s
link, not something in the file.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--path | -p | string | . | Project directory containing aetherfy.yaml |
--target | string | default | Which of the folder’s linked agents to compare with |
afy diff
afy diff --path ./services/scraper
afy diff --target stagingA deploy applies the whole file, so a field the file leaves out is compared as its
default, shown with (default), never as the value the agent had before:
nothing outside the file survives a deploy. regions are compared as a set, so
listing the same regions in another order is no change. The legend:
| Marker | Meaning |
|---|---|
~ field: old → new | The deploy would change this field |
+ field: value | The deploy would set this field (it is unset now) |
- field | The deploy would clear this field (declared null) |
= field: value | No change — local and deployed values match |
A runtime change is annotated (immutable — deploy will reject), because the
runtime is fixed by the agent’s first release that goes live.
Three cases do not reach a comparison:
| Case | What you get |
|---|---|
| The folder has no link, no such target, or a link to an agent the account lacks | The same refusals as afy deploy, naming afy init --agent |
| The agent has never been released | <agent> has no release yet: deploy it first (exit 1) |
aetherfy.yaml declares name:, description: or workspace: | Refused before any request: aetherfy.yaml declares 'name:', which a deploy refuses: the agent's name is set on the platform ('afy update <agent> --name'), not in the file. Remove it. |
afy diff exits non-zero when there are changes, which makes it a
drift gate in CI:
afy diff --path ./services/scraper
if [ $? -ne 0 ]; then
echo "Deployed Aetherfy state has drifted from aetherfy.yaml"
exit 1
fiRunning an Aetherfy task agent on demand
afy run <name> runs an agent once, immediately, outside its schedule. A
type: job agent runs its entrypoint; a type: service agent is sent one
request to its POST /aetherfy/run route — see
/agents/task-contract.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--payload | -p | string | empty | JSON payload to pass to the run |
--payload-file | -f | string | empty | Read the JSON payload from a file |
--wait | bool | false | Wait for the run to finish (exit 1 if it fails) |
--payload and --payload-file are mutually exclusive, and the payload must be
a JSON object.
# Fire and forget
afy run scraper
# With an inline payload
afy run scraper --payload '{"since":"2026-08-01","full":true}'
# With a payload file
afy run scraper --payload-file ./payload.json
# Block until the run finishes; non-zero exit if it fails
afy run scraper --waitWithout --wait, the Aetherfy CLI prints the Run ID and suggests
afy logs <name> --run <id>. With --wait, it polls for up to 30 minutes; a
failed run exits 1, and on timeout the run keeps going on Aetherfy — only the
waiting stops.
Error hints the Aetherfy CLI prints:
| Error code | Meaning and fix |
|---|---|
AGENT_NOT_DEPLOYED | The agent exists but has no deployment. Deploy it first: afy deploy. |
Listing Aetherfy run history
afy runs <name> shows the run history for an agent, newest first.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--limit | int | 20 | Maximum number of runs to show (max 100) |
afy runs scraper
afy runs scraper --limit 100
afy runs scraper --jsonColumns:
| Column | Meaning |
|---|---|
| When | When the run was started, in UTC and labelled so — the same instant --json gives as created_at |
| Trigger | What started it — cron for a scheduled fire, manual for a manual trigger, or spawn (by <agent>) for a run another agent spawned on this one |
| State | Run outcome |
| Release | The release the run executed, as afy deployments numbers it (v3). A dash when none was recorded: a service run that was never dispatched, or a run older than the field |
| Duration | Wall-clock run time |
| Run ID | Pass to afy logs <name> --run <id> |
Every run the agent executed appears here, a spawned one included: a run is the history
of the agent that executed it, and a run started by a parent through afy spawn is in the
child’s list, naming the parent. With --json each run carries spawned_by ({id, name}, or
null on a scheduled or manual run) — see /cli/spawn.
Pausing and resuming an Aetherfy scheduled task
afy schedule pause <name> pauses the agent’s scheduled task. No
scheduled runs fire until it is resumed. Manual runs via afy run are
unaffected. The command is idempotent — pausing an already-paused schedule
succeeds.
afy schedule resume <name> resumes a paused scheduled task, and is
likewise idempotent.
afy schedule pause scraper
afy schedule resume scraperBoth subcommands require the agent to have a schedule. Against one that does
not, Aetherfy answers 422 AGENT_SCHEDULE_NOT_SET and the CLI prints the fix:
add a schedule: key to aetherfy.yaml and deploy.
On resume the next run time is recomputed from now. Occurrences that elapsed while the schedule was paused are skipped, never backfilled — Aetherfy does not replay a missed window.
Both subcommands print whether anything actually changed, the resulting paused
flag, and the next run time (or (paused)). Both honour --json.
Neither command edits aetherfy.yaml. The schedule expression itself is
declared there and applied by afy deploy; see
/agents/scheduled-tasks and
/agents/aetherfy-yaml.