Skip to Content
CLIafy keys & usage
Raw

afy keys and afy usage

The afy keys command group in the Aetherfy CLI

afy keys creates, lists and revokes the API keys of your account.

SubcommandPurpose
afy keys createCreate a key by approving a code in the dashboard
afy keys listList the keys of your account
afy keys revoke <id>Revoke one key

afy keys create is the only command that makes a key, and it never makes one by itself: a person signed in to the dashboard has to approve a code first. A key cannot make another key, so a stolen key cannot be used to outlive its own revocation. afy keys list and afy keys revoke use the key the CLI is signed in with.

Creating an Aetherfy API key from the CLI

afy keys create 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 waits while you do, then prints the new key.

FlagShortTypeDefaultDescription
--namestringchosen by AetherfyName for the new key
--no-browserboolfalseDo not try to open the approval page in a browser
# Create a key for a CI system afy keys create --name ci # Print the key as JSON: {"api_key": "...", "key": {...}} afy keys create --name ci --json

The command needs no key of its own and does not use the one it has: the two requests it makes carry no credentials. The approval page names the device the CLI reported (its host name) and the name of the key, and acts only when you click APPROVE or DENY. Opening the page does nothing.

A code lives for 10 minutes and works once. The CLI asks for an answer no more often than Aetherfy allows, and the key belongs to the account that approved the code. If you approve a code and then deny it before the CLI has collected the key, no key is made.

The key is printed once, with the words “This is the only time the full key is shown.”, and stored nowhere on the machine: not in the credentials file and not in a log. Copy it when it appears. Under --json the document on stdout is the only place it is printed. To sign this machine in with a new key instead, run afy login.

If the code expires, is denied, or was already used, the command ends and says which, and what to run again. If your plan’s limit on API keys is reached, no key is made: revoke one with afy keys revoke or in the dashboard, then run the command again.

Listing Aetherfy API keys

afy keys list prints one row for each key of the account: id, name, the first characters of the key, when it was created and when it was last used (“never” if it has not been). The full key is never shown again after it is created, and a key Aetherfy manages for the account is marked (system-managed).

afy keys list afy keys list --json

--json prints the control plane’s answer unchanged: {"keys": [...]} with the fields id, name, key_prefix, created_at, last_used_at and is_system_managed.

Revoking an Aetherfy API key

afy keys revoke <id> revokes a key by its id (afy keys list shows the ids). Anything that uses the key is refused from then on, and a revoked key cannot be restored.

FlagShortTypeDefaultDescription
--yes-yboolfalseRevoke without asking

The command asks [y/N] first. When the id is the key the CLI is using, the question says so: revoking it ends this CLI’s access until you sign in again. --yes skips the question and is required when stdin is not a terminal, so a script cannot revoke by accident. Answering no exits with status 1.

afy keys revoke 3f2c9a1e-0000-0000-0000-000000000000 afy keys revoke 3f2c9a1e-0000-0000-0000-000000000000 --yes

A key that is not one of your account’s is API_KEY_NOT_FOUND (HTTP 404). The keys Aetherfy issues to your agents are not listed and cannot be revoked here.

If your account is suspended for unpaid bills, or its subscription is not active, the API refuses every request made with your keys, afy keys list and afy keys revoke included, with ACCOUNT_SUSPENDED or AUTH_SUBSCRIPTION_INACTIVE (HTTP 403). The command says so and names the page where you can still list and revoke your keys, so a key you fear is leaked can be revoked there at once: the API keys page of the dashboard .

Reading Aetherfy usage with afy usage

afy usage prints the figures of the dashboard’s Usage page for the current billing period: the period, your plan, how much of the plan has been used so far, what is owed beyond it if anything, and each agent’s awake time against its budget. The figures come from the same calculation as the dashboard, not from a second one.

afy usage afy usage --json

--json prints the control plane’s answer unchanged, with the same field names the dashboard’s usage meter uses. An account with no billing period yet prints a sentence saying so, and hasActivePeriod is false in the JSON.

Errors from afy keys and afy usage

CodeHTTP statusMeaning
AUTH_AGENT_KEY_OUT_OF_SCOPE403The key is an agent’s own key, which can call neither afy keys nor afy usage
ACCOUNT_SUSPENDED403The account is suspended for unpaid bills; keys can still be listed and revoked in the dashboard
AUTH_SUBSCRIPTION_INACTIVE403The subscription is not active; keys can still be listed and revoked in the dashboard
API_KEY_NOT_FOUND404afy keys revoke was given an id that is not one of your keys
API_KEY_LIMIT_REACHED400Your plan’s limit on API keys is reached, so no key was made
NO_ACTIVE_SUBSCRIPTION400The account that approved the code has no subscription, so no key was made. Contact support
DEVICE_CODE_EXPIRED410The code was not approved within 10 minutes
DEVICE_ACCESS_DENIED403The code was denied, or its approval was taken back before the key was collected
DEVICE_CODE_ALREADY_USED409The key for this code was already collected
DEVICE_CODE_NOT_FOUND404Aetherfy does not know this code
DEVICE_CODE_ALREADY_DECIDED409Another account already approved or denied this code
DEVICE_POLLING_TOO_FAST429The CLI asked sooner than the interval allows; it waits and asks again
RATE_LIMIT_EXCEEDED429Too many requests from your address; wait the number of seconds in Retry-After
SERVICE_UNAVAILABLE503Aetherfy could not answer right now; the CLI waits the number of seconds in Retry-After and tries again

The full list, with the HTTP statuses of every code, is the agents API error reference.

Last updated on