Aetherfy CLI

Installing the Aetherfy CLI

The Aetherfy CLI is a single Go binary named afy. It is distributed as source from the module github.com/aetherfy/cli and licensed Apache 2.0. Building it requires Go 1.21 or newer.

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

make install compiles the binary and installs it as afy on your PATH. Confirm the install:

afy version

Prebuilt archives are also attached to the GitHub releases of the Aetherfy CLI at https://github.com/aetherfy/cli/releases  if you prefer a binary to a source build.

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 afy_live_... or afy_test_... — the prefix 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, 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.

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 rollback, afy spawn, afy deployments, afy agents 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 agents diff exiting 1 on any difference is deliberate and makes it usable as a CI drift gate:

afy agents 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