Skip to Content
CLIAgent commands
Raw

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.

SubcommandPurpose
afy listList 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 diffCompare 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 the schedule: key in aetherfy.yaml and applied by afy deploy. See /agents/scheduled-tasks.
  • There is no afy pause or afy resume. The pause and resume verbs for an agent are afy stop and afy start.
  • afy rename and afy pull are gone. Renaming is afy update <name> --name; exporting an agent’s configuration is afy init --agent <name>, which writes it as aetherfy.yaml in 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 --json

The default columns are:

ColumnMeaning
NameThe agent name
TypeSERVICE or JOB
StatusCurrent lifecycle status
RegionsThe regions the agent is deployed in
IDThe 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.

ColumnRendering
ScheduleThe declared schedule expression
Next RunA UTC timestamp, or (paused) when the schedule is paused
Last RunThe 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.

FlagShortTypeDefaultDescription
--description-dstringemptyAgent description
--workspacestringemptyThe 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.

FlagShortTypeDefaultDescription
--yes-yboolfalseDelete 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 --yes

If 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-gateway

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

readinessWhat afy start tells you
servingThe agent resumed and is serving requests
startingThe agent resumed; your code is still starting, and requests sent now are held until it is listening
load_failedThe agent resumed, but your code failed to load, so its requests will fail — afy logs <name> has the error
unconfirmedThe 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_startThe agent resumed, but starting its machines took longer than it should, so your code was not checked — the delay was on Aetherfy’s side
nullA 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" ;; esac

A 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 retrying

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

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 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 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 --json

The text output covers:

FieldNotes
IDThe Aetherfy agent ID
NameThe agent name
TypeSERVICE or JOB
StatusCurrent lifecycle status, with health or degraded detail when present
ReasonWhy 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
WarningOne 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
RegionsThe regions the agent is deployed in
Spawn EnabledWhether this agent may start child agents
WorkspaceThe workspace the agent lives in
ScheduleThe schedule expression, labelled UTC
Next runNext scheduled fire time, or (paused)
Last tickWhat 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 runThe 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
CreatedCreation timestamp
UpdatedLast-modified timestamp
DescriptionThe agent description
Spawn relationshipsParent and child agents
Last deploy, Deploy errorOnly 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 idThe agent’s GitHub link, when it has one

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 saysWhat happenedWhat fixes it
GitHub disconnected — pushes are not deployingThe Aetherfy account is no longer connected to GitHubafy github connect. The link is kept, so deploys resume on reconnect
Branch deleted — pushes are not deployingThe branch the link watches was deleted, and status names which and whenRecreate the branch and push. Relinking would succeed and change nothing
Auto-deploy paused since <time> — pushes are not deployingYou paused auto-deploy on the link with afy github pause. The link is kept, and the warning can show beside either of the other twoafy 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 ends

A 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 ready

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

FlagShortTypeDefaultDescription
--namestringemptyRename the agent
--workspacestringemptyMove the agent to this workspace (redeploys it)
--description-dstringemptySet the agent’s description
--yes-yboolfalseMove 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
FlagDefaultEffect
--add—Grant a workspace, by name. Repeat it, or give a comma-separated list
--remove—Revoke a granted workspace, the same way
--levelread for a new grantThe 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, -yfalseChange without asking
--jsonfalsePrint 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.

FlagShortTypeDefaultDescription
--path-pstring.Project directory containing aetherfy.yaml
--targetstringdefaultWhich of the folder’s linked agents to compare with
afy diff afy diff --path ./services/scraper afy diff --target staging

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

MarkerMeaning
~ field: old → newThe deploy would change this field
+ field: valueThe deploy would set this field (it is unset now)
- fieldThe deploy would clear this field (declared null)
= field: valueNo 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:

CaseWhat you get
The folder has no link, no such target, or a link to an agent the account lacksThe 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 fi

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

FlagShortTypeDefaultDescription
--payload-pstringemptyJSON payload to pass to the run
--payload-file-fstringemptyRead the JSON payload from a file
--waitboolfalseWait 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 --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:

Error codeMeaning and fix
AGENT_NOT_DEPLOYEDThe 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.

FlagShortTypeDefaultDescription
--limitint20Maximum number of runs to show (max 100)
afy runs scraper afy runs scraper --limit 100 afy runs scraper --json

Columns:

ColumnMeaning
WhenWhen the run was started, in UTC and labelled so — the same instant --json gives as created_at
TriggerWhat 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
StateRun outcome
ReleaseThe 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
DurationWall-clock run time
Run IDPass 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 scraper

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

Last updated on