Skip to Content
CLIInstall & authentication
Raw

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

https://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:

VariableDefaultEffect
AETHERFY_INSTALL_DIR/usr/local/binDirectory the afy binary is written to
AETHERFY_VERSIONlatestVersion 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" bash

Install script — Windows

irm https://aetherfy.com/install.ps1 | iex

https://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:

VariableDefaultEffect
AETHERFY_INSTALL_DIR%LOCALAPPDATA%\Programs\afyDirectory afy.exe is written to
AETHERFY_VERSIONlatestVersion 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 | iex

Windows 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 version

Updating 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.0

The 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”.

FlagShortTypeDefaultDescription
--api-keystringemptyAPI key to sign in with
--no-browserboolfalseDo 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 login

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

CommandBehaviour
afy logoutRemoves the stored credentials. No flags. Prints Not currently logged in. when there are none.
afy whoamiShows 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:

  1. $AETHERFY_CONFIG_DIR, if set.
  2. On Windows, %APPDATA%\aetherfy.
  3. On Linux, $XDG_CONFIG_HOME/aetherfy, if XDG_CONFIG_HOME is set.
  4. 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.

KeyDefault
api_urlhttps://agents.aetherfy.com/api/v1
default_regionus-east-1
output_formattext
no_colorfalse
verbosefalse

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

Environment variables read by the Aetherfy CLI

VariableEffect
AETHERFY_API_KEYAPI 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_DIROverrides the config directory.
NO_COLORAny non-empty value disables coloured output.
XDG_CONFIG_HOMEConfig directory base on Linux.
APPDATAConfig directory base on Windows.
AETHERFY_API_URLOverrides the api_url config key.
AETHERFY_DEFAULT_REGIONOverrides the default_region config key.
AETHERFY_OUTPUT_FORMATOverrides the output_format config key.
AETHERFY_NO_COLOROverrides the no_color config key.
AETHERFY_VERBOSEOverrides the verbose config key.
AETHERFY_VECTORS_URLVectors API endpoint for the vector commands. See /cli/vectors.
AETHERFY_VECTORS_API_REGIONVectors 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 --yes

Global flags of the Aetherfy CLI

These persistent flags are accepted by every Aetherfy CLI command.

FlagShortTypeDefaultDescription
--api-urlstringemptyAPI base URL (overrides config)
--jsonboolfalsePrint the result as JSON on stdout (see below)
--verbose-vboolfalseVerbose output
--no-colorboolfalseDisable 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:

RuleDetail
stdoutCarries 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
Streamsafy logs --follow prints one compact JSON object per line
ErrorsOne 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 codesThe same with and without --json (see below)
Several resultsA 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 completionPrints a shell script, so it refuses --json (exit 2)
Empty listsAn empty list is [], never null and never text

Exit codes of the Aetherfy CLI

CodeWhen
0Success
1A 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
2Input 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
3Not logged in
4afy 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 archive and afy restore retry a RESOURCE_BUSY up to five times, waiting 2, 4, 8 and 16 seconds;
  • afy index create retries 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 answerThe message saysWhat 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 backCheck the network or proxy, then run the command again
JSON of a shape this version of afy does not understandthe server answered in a format this version of afy does not understand (...). Update afy: run 'afy upgrade', with the decoding detail in the bracketsRun 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-Expression

To 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 version

Where to go next with the Aetherfy CLI

PageWhat it covers
/cli/agentsEvery agent verb — lifecycle, status, update, access, schedules, runs, diff
/cli/deployafy init, afy deploy, the link file, afy deployments, afy rollback
/cli/logsafy logs and its filters
/cli/secretsafy secrets — agent-scoped and workspace-scoped
/cli/keysafy keys and afy usage — create a key by approving a code, list, revoke, and the usage meter
/cli/workspacesafy workspaces
/cli/githubafy github — connect, link, pause and resume auto-deploy
/cli/spawnafy spawn — parent agents starting child agents
/cli/vectorsafy collections, afy index, afy points — the vector database
/agents/aetherfy-yamlThe aetherfy.yaml manifest the CLI reads and writes
/platform/limitsPlan quotas and per-request caps
Last updated on