afy agents

The afy agents command group in the Aetherfy CLI

afy agents manages the lifecycle of Aetherfy agents. The group has two aliases, agent and a, so afy a list and afy agents list are the same command.

Two things do not exist in the Aetherfy CLI and are commonly assumed:

• There is no afy agents schedule set. A schedule is declared with the schedule: key in aetherfy.yaml and applied by afy deploy. See /agents/scheduled-tasks.
• There is no afy agents pause or afy agents resume. The pause and resume verbs for an agent are afy agents stop and afy agents start.

Listing Aetherfy agents

afy agents list prints every agent in the account. It takes no arguments and no flags of its own.

afy agents list
afy agents list -o json

The default columns are:

When at least one agent in the account has a scheduled task, the table grows to eight columns: Name, Type, Status, Region, Schedule, Next Run, Last Run, ID.

A status of usage_paused renders as paused (usage limit) — the agent was paused by the Aetherfy usage meter, not by afy agents stop.

Creating an Aetherfy agent

afy agents create <name> creates the agent record. It takes exactly one positional argument, the name.

--type accepts only SERVICE or JOB; anything else is rejected.

afy agents create scraper \
  --type JOB \
  --runtime python3.12 \
  --description "Nightly catalogue scrape"

afy agents create has no --workspace flag. To put a new Aetherfy agent in a workspace, either run afy agents update <name> --workspace <ws> afterwards, or declare the workspace: key in aetherfy.yaml before deploying.

Deleting an Aetherfy agent

afy agents delete <name> permanently deletes the agent.

Without --force the Aetherfy CLI asks for confirmation and requires you to type the agent name exactly before it proceeds.

afy agents delete scraper
afy agents delete scraper --force

If your goal is to free a plan quota slot rather than lose the agent, use afy agents archive instead — it preserves the configuration and the stored code bundle.

Pausing and resuming an Aetherfy agent with stop and start

afy agents 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 agents start <name> resumes an agent that was paused with stop.

afy agents stop api-gateway
afy agents start api-gateway

Neither command takes flags. 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 agents 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 agents restore <name> re-provisions an archived Aetherfy agent from the preserved bundle.

afy agents archive old-worker
afy agents restore old-worker

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

Cancelling a pending Aetherfy deployment

afy agents cancel <name> cancels a pending deployment for the agent. It takes no flags.

afy agents cancel scraper

Only 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 agents status <name> prints the detailed state of a single Aetherfy agent. It takes no flags of its own and honours -o json.

afy agents status scraper
afy agents status scraper -o json

The text output covers:

Renaming an Aetherfy agent

afy agents rename <current-name> <new-name> changes the agent’s name. It takes exactly two positional arguments, which must differ.

afy agents rename scraper catalogue-scraper --force

The Aetherfy agent URL is not derived from the name and does not change, so existing integrations, links, and webhooks keep working across a rename. Only the name changes.

Updating an Aetherfy agent’s workspace or description

afy agents update <name> changes the mutable metadata of an Aetherfy agent.

Rules enforced by the Aetherfy CLI:

• At least one flag is required; with none, the command errors.
• --workspace and --no-workspace are mutually exclusive.
• --workspace "" is rejected. Use --no-workspace to clear the assignment.

afy agents update scraper --workspace research
afy agents update scraper --no-workspace
afy agents update scraper -d "Nightly catalogue scrape"

This is also the supported way to move an existing Aetherfy agent into a workspace, because afy agents create has no --workspace flag.

Exporting an Aetherfy agent’s configuration with pull

afy agents pull <agent-name> exports the agent’s current configuration in aetherfy.yaml form. By default it writes to stdout so it can be redirected.

Warning: on afy agents pull alone, -o means an output file path, not the global Aetherfy output format. afy agents pull scraper -o json writes a file named json. This subcommand shadows the global --output flag.

# To stdout
afy agents pull scraper
 
# Redirect
afy agents pull scraper > aetherfy.yaml
 
# Or write directly
afy agents pull scraper -o aetherfy.yaml

The emitted YAML is the declarative subset only — fields the Aetherfy server derives are excluded. Re-deploying the pulled file is therefore a no-op against the agent it came from.

Diffing local aetherfy.yaml against deployed Aetherfy state

afy agents diff compares the local aetherfy.yaml against the agent’s current state on Aetherfy and prints what a deploy would change under merge-patch semantics. It takes no positional arguments — the agent is identified from the manifest.

afy agents diff
afy agents diff --path ./services/scraper

The output legend:

A runtime change is annotated (immutable — deploy will reject), because the Aetherfy runtime cannot be changed on an existing agent.

afy agents diff exits non-zero when there are changes, which makes it a drift gate in CI:

afy agents diff --path ./services/scraper
if [ $? -ne 0 ]; then
  echo "Deployed Aetherfy state has drifted from aetherfy.yaml"
  exit 1
fi

Running an Aetherfy task agent on demand

afy agents run <name> runs a task agent once, immediately, outside its schedule. Only deployed agents declared as type: job can be run this way.

--payload and --payload-file are mutually exclusive, and the payload must be a JSON object.

# Fire and forget
afy agents run scraper
 
# With an inline payload
afy agents run scraper --payload '{"since":"2026-08-01","full":true}'
 
# With a payload file
afy agents run scraper --payload-file ./payload.json
 
# Block until the run finishes; non-zero exit if it fails
afy agents run scraper --wait

Without --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:

Listing Aetherfy run history

afy agents runs <name> shows the run history for an agent, newest first.

afy agents runs scraper
afy agents runs scraper --limit 100
afy agents runs scraper -o json

Columns:

Only scheduled and manual runs appear here. Runs started by a parent agent through afy spawn belong to the parent’s history and are deliberately excluded from the child’s list — see /cli/spawn.

Pausing and resuming an Aetherfy scheduled task

afy agents schedule pause <name> pauses the agent’s scheduled task. No scheduled runs fire until it is resumed. Manual runs via afy agents run are unaffected. The command is idempotent — pausing an already-paused schedule succeeds.

afy agents schedule resume <name> resumes a paused scheduled task, and is likewise idempotent.

afy agents schedule pause scraper
afy agents schedule resume scraper

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