Aetherfy CLI
Installing the Aetherfy CLI
The Aetherfy CLI is a single Go binary named afy, licensed Apache 2.0. Install it
with the install script for your system, below; that is the one recommended path.
GitHub Releases is the fallback, for a machine where the script cannot run. Building
the Aetherfy CLI from source is covered in
the Aetherfy CLI’s README , not
here.
A coding agent that installs the Aetherfy CLI for you may be unable to run a piped
command such as curl … | bash: some agent harnesses refuse it. You can approve the
command yourself, or use the GitHub Releases steps below. See
/platform/ai.
Install script — Linux and macOS
curl -fsSL https://aetherfy.com/install.sh | bashhttps://aetherfy.com/install.sh redirects to the installer kept beside the
Aetherfy CLI’s source, so the one-liner always serves the current script. It is
Linux and macOS only: under Git Bash, MSYS or Cygwin it refuses to run, and the
refusal hands you the PowerShell one-liner below, then the releases page and the
README as fallbacks. macOS is supported on Intel and Apple Silicon: both builds
are published.
Two environment variables control it:
| Variable | Default | Effect |
|---|---|---|
AETHERFY_INSTALL_DIR | /usr/local/bin | Directory the afy binary is written to |
AETHERFY_VERSION | latest | Version to install. 0.1.0 and v0.1.0 both name the same release |
curl -fsSL https://aetherfy.com/install.sh | AETHERFY_INSTALL_DIR="$HOME/.local/bin" bashInstall script — Windows
irm https://aetherfy.com/install.ps1 | iexhttps://aetherfy.com/install.ps1 redirects to the PowerShell installer kept
beside the Aetherfy CLI’s source. It writes afy.exe to
%LOCALAPPDATA%\Programs\afy and adds that directory to your user PATH, so it
needs no administrator rights and afy works in the terminal you ran it from.
The same two environment variables control it:
| Variable | Default | Effect |
|---|---|---|
AETHERFY_INSTALL_DIR | %LOCALAPPDATA%\Programs\afy | Directory afy.exe is written to |
AETHERFY_VERSION | latest | Version to install. 0.1.0 and v0.1.0 both name the same release |
$env:AETHERFY_VERSION = "0.1.0"
irm https://aetherfy.com/install.ps1 | iexWindows on ARM has no published Aetherfy CLI build. The installer says so rather than downloading an archive that does not exist — run the amd64 build under x64 emulation.
GitHub Releases — the fallback
Use this when the install script cannot run: a locked-down machine, a harness that
refuses a piped command, or an architecture the scripts do not serve. Download the
archive for your platform from
the Aetherfy CLI’s releases page
(afy-linux-amd64.tar.gz, afy-darwin-arm64.tar.gz, afy-windows-amd64.zip and
so on), extract it, and then put afy in a directory on your PATH. The archive
extracting is not the install: until the binary is on your PATH, a terminal
answers afy: command not found.
On Linux and macOS, from the directory you downloaded the archive to:
tar -xzf afy-linux-amd64.tar.gz
mkdir -p "$HOME/.local/bin"
mv ./afy "$HOME/.local/bin/afy"Then make sure $HOME/.local/bin is on your PATH (add
export PATH="$HOME/.local/bin:$PATH" to your shell’s startup file and open a new
terminal). Any other directory already on your PATH, such as /usr/local/bin
(which needs sudo), works the same way.
On Windows, in PowerShell, from the directory you downloaded the archive to:
Expand-Archive afy-windows-amd64.zip -DestinationPath "$env:LOCALAPPDATA\Programs\afy"
[Environment]::SetEnvironmentVariable(
"Path",
[Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\Programs\afy",
"User")Open a new terminal afterwards: a terminal that was already open keeps the PATH it
started with. Pin a version by downloading that version’s release rather than the
latest.
Confirming an Aetherfy CLI install
Whichever path you took, the install answers:
afy versionUpdating the Aetherfy CLI
afy upgrade replaces the running binary with the newest published Aetherfy CLI
release. It needs no Aetherfy account — updating the CLI is not an authenticated
operation.
afy update is a different command. It changes an Aetherfy agent’s
name, workspace or description and takes an agent name. The two are not aliases and
neither falls back to the other, so afy update with no arguments reports a
missing agent name rather than looking for a release. See
/cli/agents.
# Replace this binary with the newest release
afy upgrade
# Report whether anything newer exists; change nothing
afy upgrade --check
# Install a specific version — 0.1.0 and v0.1.0 both work
afy upgrade --version 0.1.0The download is checked against the release’s checksums.txt before anything is
extracted, and a mismatch refuses to install — the same rule the Aetherfy
install script follows.
A build from source is refused. If afy version reports dev or a Go
module pseudo-version (v0.0.0-<date>-<sha>), this binary was built from source
rather than installed from a release. Replacing it with a release archive would
discard the build you have, so afy upgrade stops and tells you how the binary was
installed. Update it the way you built it — or pass --force if replacing it with a
release is what you want.
Authenticating the Aetherfy CLI
afy login signs the Aetherfy CLI in. Its short description is “Sign in to
Aetherfy”.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--api-key | string | empty | API key to sign in with | |
--no-browser | bool | false | Do not try to open the approval page in a browser |
With no key to hand, afy login prints a code and a page. Open the page in a
browser where you are signed in to Aetherfy, check that it shows the same code
and approve it; the CLI then creates a key for this machine and stores it. The
code lives for 10 minutes and works once, and the key belongs to the account
that approved it. The steps, the flags and the errors are those of
afy keys create, which
is the same sign-in without storing the key.
To sign in with a key you already have, pass it with --api-key or pipe it on
stdin; a terminal is not read, so there is no prompt for a key. The key
format is validated locally, then the Aetherfy API is called to confirm the key
is real. The Aetherfy CLI accepts either issuing-environment prefix,
afy_live_... or afy_test_..., followed by at least 32 alphanumeric
characters. That is a deliberately permissive client-side check, not the issued
format: Aetherfy generates the prefix plus exactly 32 hexadecimal characters,
and keys you create carry the afy_live_ prefix — documented at
/platform/api-keys. List and revoke keys with
afy keys, or at
https://app.aetherfy.com/dashboard/settings/api-keys .
# Sign in by approving a code in the dashboard
afy login
# The same, without opening a browser from here
afy login --no-browser
# Sign in with a key you already have
afy login --api-key afy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# The same, from a pipe
echo "$AFY_KEY" | afy loginOn success the credentials are written to credentials.yaml inside the Aetherfy
config directory with file permissions 0600. Logging in with a afy_test_ key
prints the warning Using test API key - requests will be in test mode. You are
unlikely to meet that warning: afy_test_ keys are issued only by Aetherfy’s own
pre-production environments, and every key you create carries the afy_live_
prefix. Test mode changes more than that warning for an agent deployed with a
afy_test_ key: it runs in a separate hosting organization and is recorded in
a separate database, its schedules fire only through Aetherfy’s internal trigger
because no scheduler sweeps test-mode agents, and its AETHERFY_VECTORS_URL is
the vector database in its region on that organization’s own private network,
not the address a live agent receives.
| Command | Behaviour |
|---|---|
afy logout | Removes the stored credentials. No flags. Prints Not currently logged in. when there are none. |
afy whoami | Shows the current authentication status. No flags. It prints the masked API key, the key type (test or live), the API URL and the path to the credentials file, and reads the account’s email and plan from the API on every run, so they are right whether the key came from afy login or AETHERFY_API_KEY, and right after a plan change. Nothing about the plan is stored on the machine. When the API cannot be asked, or refuses the key, the command fails like any other. |
The Aetherfy CLI configuration directory
The Aetherfy CLI resolves its configuration directory in this order:
$AETHERFY_CONFIG_DIR, if set.- On Windows,
%APPDATA%\aetherfy. - On Linux,
$XDG_CONFIG_HOME/aetherfy, ifXDG_CONFIG_HOMEis set. - Otherwise,
~/.aetherfy.
The directory is created with mode 0700. It holds two files: config.yaml
(settings) and credentials.yaml (the stored API key, mode 0600).
The Aetherfy CLI config file
Settings live in <config dir>/config.yaml. Every key has a default, so the file
is optional.
| Key | Default |
|---|---|
api_url | https://agents.aetherfy.com/api/v1 |
default_region | us-east-1 |
output_format | text |
no_color | false |
verbose | false |
A complete Aetherfy config.yaml:
api_url: https://agents.aetherfy.com/api/v1
default_region: us-east-1
output_format: text
no_color: false
verbose: falseEnvironment variables read by the Aetherfy CLI
| Variable | Effect |
|---|---|
AETHERFY_API_KEY | API key. Highest priority — it is checked before the credentials file, so it overrides afy login. Inside an Aetherfy agent it holds the agent’s own injected key, which the agents API limits; see agent-scoped keys for what it may call and how to run the CLI there with account access. |
AETHERFY_CONFIG_DIR | Overrides the config directory. |
NO_COLOR | Any non-empty value disables coloured output. |
XDG_CONFIG_HOME | Config directory base on Linux. |
APPDATA | Config directory base on Windows. |
AETHERFY_API_URL | Overrides the api_url config key. |
AETHERFY_DEFAULT_REGION | Overrides the default_region config key. |
AETHERFY_OUTPUT_FORMAT | Overrides the output_format config key. |
AETHERFY_NO_COLOR | Overrides the no_color config key. |
AETHERFY_VERBOSE | Overrides the verbose config key. |
AETHERFY_VECTORS_URL | Vectors API endpoint for the vector commands. See /cli/vectors. |
AETHERFY_VECTORS_API_REGION | Vectors API region for the vector commands, resolved by region discovery. |
Setting AETHERFY_API_KEY is the usual way to run the Aetherfy CLI in CI, where
there is no interactive login and no writable home directory:
export AETHERFY_API_KEY=afy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
afy deploy --yesGlobal flags of the Aetherfy CLI
These persistent flags are accepted by every Aetherfy CLI command.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--api-url | string | empty | API base URL (overrides config) | |
--json | bool | false | Print the result as JSON on stdout (see below) | |
--verbose | -v | bool | false | Verbose output |
--no-color | bool | false | Disable coloured output |
The root command also accepts --version, which prints the same information as
afy version.
JSON output of the Aetherfy CLI
Text is the default. One switch, --json, is accepted by every command; there is no
-o or --output. With --json:
| Rule | Detail |
|---|---|
| stdout | Carries only JSON: the command’s result, on success. Hints, progress, warnings and prompts go to stderr, so afy list --json | jq never has to filter anything. A command that waits (afy deploy, afy redeploy, afy rollback) prints one document, the deployment as it settled |
| Streams | afy logs --follow prints one compact JSON object per line |
| Errors | One JSON object on stderr, with stdout left empty: {"error": {"status": 409, "code": "AGENT_PAUSED_CANNOT_MOVE", "message": "Agent 'bot' is paused; resume it before moving it."}}. status and code are the server’s when it sent them, so act on code, not on the sentence. A refused filter key (INVALID_FILTER, or INVALID_REQUEST_FIELD for a request member) adds field, the path of the key in the request, key, the key as sent, and suggestion, the nearest valid key when there is one; each is present only when the server sent it. A refusal the CLI raises itself, for input it refused before sending anything (exit 2), has the code CLI_USAGE_ERROR, a message and no status; so does the CLI’s refusal of an answer that lacks what the control plane’s contract promises (afy logs with no stated retention), with the code CLI_RESPONSE_INVALID; a question the person answered no (exit 1) has the code CLI_CANCELLED, a message and no status. Without --json, an error is the text Error: ... |
| Exit codes | The same with and without --json (see below) |
| Several results | A command that reports per-item results (afy secrets set A=1 B=2) writes them as its one document and exits 1 when any item was refused. This is the one failure where stdout is not empty |
afy completion | Prints a shell script, so it refuses --json (exit 2) |
| Empty lists | An empty list is [], never null and never text |
Exit codes of the Aetherfy CLI
| Code | When |
|---|---|
| 0 | Success |
| 1 | A refused or failed operation. That includes afy deploy, afy redeploy and afy rollback (also when the deployment they wait for fails, or the wait runs out before it finishes), afy run --wait when the run fails, afy diff when there are differences, afy workspaces regions when the change is refused or a change --wait follows fails, afy secrets set when a key was not stored, and a command whose answer from the control plane lacks what its contract promises (afy logs with no stated retention: nothing is printed to stdout, and under --json the error carries the code CLI_RESPONSE_INVALID). Also any command whose question the person answered no: the six deletes (afy delete, afy workspaces delete, afy secrets delete, afy collections delete, afy collections schema delete, afy points delete), afy keys revoke, afy access, afy collections regions, the overage question of afy deploy and the overwrite question of afy init: Cancelled, nothing deleted, and under --json an error document with the code CLI_CANCELLED, a message and no status |
| 2 | Input refused before anything was sent: a command line the CLI cannot parse (an unknown flag or command, a flag without its value or with a value of the wrong type, too few or too many arguments, a required flag not set), a group such as afy secrets or afy workspaces given a word that is none of its subcommands, afy update or afy workspaces update with nothing to change, a command that asks run without a terminal and without its skip flag (the ones above: refused before it asks, with This <what it does>; pass --yes to confirm without a prompt., or --force for afy init’s overwrite), and bad arguments to a vector command (afy collections, afy index, afy points; see /cli/vectors), afy secrets, afy spawn, afy run or afy login, and the like. Under --json the error line carries the code CLI_USAGE_ERROR |
| 3 | Not logged in |
| 4 | afy start --wait reached the server’s bound with the start still pending: Aetherfy is still retrying it, and afy status <name> shows the result. Also --wait on afy collections regions, afy collections move and afy workspaces regions when the change is still running after 30 minutes; it keeps running |
A command that prints an error exits non-zero, and the exit code is the same with
and without --json.
When Aetherfy answers 503 because it is briefly busy or its database cannot be reached
(RESOURCE_BUSY or SERVICE_UNAVAILABLE), the CLI prints the platform’s sentence and
exits 1. Wait a few seconds and run it again. Some commands retry for you first:
afy stop,afy start,afy archiveandafy restoreretry aRESOURCE_BUSYup to five times, waiting 2, 4, 8 and 16 seconds;afy index createretries any 503 within its own deadline.
Every other command answers at once.
When the answer is not one the CLI can read
A request the CLI reads (a GET) is repeated, up to twice, only when the connection itself failed:
it could not connect, it timed out, or the answer was cut off before it ended. An answer that
arrived whole and cannot be used is never repeated, because asking again returns the same
bytes. It stops at once, exits with code 1, and says what to do:
| The answer | The message says | What to do |
|---|---|---|
Complete, but not JSON (for example text/html, from a Wi-Fi login page or a proxy) | the answer did not come from the Aetherfy API: it is text/html, not JSON. Check the network or proxy (a Wi-Fi login page or a proxy answers like this), naming the content type that came back | Check the network or proxy, then run the command again |
JSON of a shape this version of afy does not understand | the server answered in a format this version of afy does not understand (...). Update afy: run 'afy upgrade', with the decoding detail in the brackets | Run afy upgrade |
afy diff exiting 1 on any difference is deliberate and makes it usable
as a CI drift gate:
afy diff --path ./my-agent || echo "aetherfy.yaml differs from deployed state"Shell completion for the Aetherfy CLI
afy completion [bash|zsh|fish|powershell] writes a completion script to stdout.
It takes exactly one argument, restricted to those four shells.
# Bash
source <(afy completion bash)
# Zsh
source <(afy completion zsh)
# Fish
afy completion fish | source# PowerShell
afy completion powershell | Out-String | Invoke-ExpressionTo make completion permanent, add the matching line to your shell’s startup file or write the Aetherfy script into your shell’s completion directory.
Version information from the Aetherfy CLI
afy version prints the Aetherfy CLI version, the commit, the build date, the Go
version it was built with, and the platform. It takes no flags.
afy versionWhere to go next with the Aetherfy CLI
| Page | What it covers |
|---|---|
| /cli/agents | Every agent verb — lifecycle, status, update, access, schedules, runs, diff |
| /cli/deploy | afy init, afy deploy, the link file, afy deployments, afy rollback |
| /cli/logs | afy logs and its filters |
| /cli/secrets | afy secrets — agent-scoped and workspace-scoped |
| /cli/keys | afy keys and afy usage — create a key by approving a code, list, revoke, and the usage meter |
| /cli/workspaces | afy workspaces |
| /cli/github | afy github — connect, link, pause and resume auto-deploy |
| /cli/spawn | afy spawn — parent agents starting child agents |
| /cli/vectors | afy collections, afy index, afy points — the vector database |
| /agents/aetherfy-yaml | The aetherfy.yaml manifest the CLI reads and writes |
| /platform/limits | Plan quotas and per-request caps |