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.
| Subcommand | Purpose |
|---|---|
afy keys create | Create a key by approving a code in the dashboard |
afy keys list | List 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.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--name | string | chosen by Aetherfy | Name for the new key | |
--no-browser | bool | false | Do 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 --jsonThe 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.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--yes | -y | bool | false | Revoke 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 --yesA 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
| Code | HTTP status | Meaning |
|---|---|---|
AUTH_AGENT_KEY_OUT_OF_SCOPE | 403 | The key is an agent’s own key, which can call neither afy keys nor afy usage |
ACCOUNT_SUSPENDED | 403 | The account is suspended for unpaid bills; keys can still be listed and revoked in the dashboard |
AUTH_SUBSCRIPTION_INACTIVE | 403 | The subscription is not active; keys can still be listed and revoked in the dashboard |
API_KEY_NOT_FOUND | 404 | afy keys revoke was given an id that is not one of your keys |
API_KEY_LIMIT_REACHED | 400 | Your plan’s limit on API keys is reached, so no key was made |
NO_ACTIVE_SUBSCRIPTION | 400 | The account that approved the code has no subscription, so no key was made. Contact support |
DEVICE_CODE_EXPIRED | 410 | The code was not approved within 10 minutes |
DEVICE_ACCESS_DENIED | 403 | The code was denied, or its approval was taken back before the key was collected |
DEVICE_CODE_ALREADY_USED | 409 | The key for this code was already collected |
DEVICE_CODE_NOT_FOUND | 404 | Aetherfy does not know this code |
DEVICE_CODE_ALREADY_DECIDED | 409 | Another account already approved or denied this code |
DEVICE_POLLING_TOO_FAST | 429 | The CLI asked sooner than the interval allows; it waits and asks again |
RATE_LIMIT_EXCEEDED | 429 | Too many requests from your address; wait the number of seconds in Retry-After |
SERVICE_UNAVAILABLE | 503 | Aetherfy 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.