Aetherfy CLI

Installing the Aetherfy CLI

The Aetherfy CLI is a single Go binary named afy, licensed Apache 2.0. There are four ways to install it. The install script is the one to reach for; the release archive is the one to reach for when you are pinning a version or installing somewhere the script does not write.

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.

Two environment variables control it:

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:

$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, or build from source.

GitHub Releases

Download the archive for your platform from the Aetherfy CLI’s releases page , extract it, and put afy somewhere on your PATH. Use this to pin a version by hand, or to install the Aetherfy CLI somewhere the scripts above do not reach.

go install

Requires Go 1.24 or newer. It compiles the Aetherfy CLI from source rather than downloading a published archive, which is what you want to track main or to build for a platform the release does not carry:

go install github.com/l-td/aetherfy-cli/cmd/afy@latest

The cmd/afy suffix is mandatory, not decoration. Go names the installed binary after the package directory it built, so the module-root form installs one called aetherfy-cli instead — and then every afy ... command in this documentation fails with afy: command not found on a machine where the install plainly succeeded. Install .../cmd/afy@latest.

The binary lands in $(go env GOPATH)/bin; make sure that directory is on your PATH.

From source

Requires Go 1.24 or newer, and a make — on Windows, Git Bash or WSL:

git clone https://github.com/l-td/aetherfy-cli.git
cd aetherfy-cli
make install

make install prints the directory it installed into. That directory is not on your PATH by default, and that is the usual reason a successful build is followed by afy: command not found.

Confirming an Aetherfy CLI install

Whichever path you took, the install answers:

afy version

The Go version required, the platform prerequisites, and exactly where the binary lands are maintained beside the build itself, in the Aetherfy CLI’s installation instructions .

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 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 came from go install, make install or go build rather than 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 same way you installed it — or pass --force if replacing it with a release is what you want.

Authenticating the Aetherfy CLI

afy login authenticates the Aetherfy CLI with an API key. Its short description is “Authenticate with your Aetherfy API key”.

When --api-key is absent the command prompts for the key on stdin. 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. Create and revoke keys at https://app.aetherfy.com/dashboard/settings/api-keys .

# Interactive — prompts for the key
afy login
 
# Non-interactive
afy login --api-key afy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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.

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.

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

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.

The root command also accepts --version, which prints the same information as afy version.

Output formats in the Aetherfy CLI

-o text is the default. -o table is accepted, but list output is already rendered as a table, so it changes nothing.

-o json is honoured by exactly these Aetherfy commands:

Every other Aetherfy command prints text regardless of -o.

Three quirks are worth knowing before you parse Aetherfy CLI output in a script:

Exit codes of the Aetherfy CLI

Exit codes are not uniform across the Aetherfy CLI, and scripts must not assume they are. Several commands print an Error: line and still exit 0: afy logs, afy secrets, afy spawn, afy deployments, afy runs, and afy login. Only the commands listed under code 1, plus the authentication gate that returns 3, guarantee a non-zero status on failure.

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