# @kody/fly

## Intent

Official Fly.io helpers so Kody agents can inspect **the caller's** organizations,
apps, Machines, logs, and Prometheus metrics — not a shared platform org. Auth
is a saved API token, not OAuth. Reads are free-form. Machine start, stop, and
destroy support `dryRun: true`; destroy also requires `confirm: true`.

This listing is meant to be forked. After you fork, save your own `flyApiToken`
and call the helpers in your account. No Fly app names or organization slugs
are baked into the package.

Share this listing as https://kody.codes/@kody/fly

## What it does

- List or resolve organizations via GraphQL
- List/get apps and Machines via Machines REST
- Start/stop/destroy Machines with `dryRun` (destroy also needs `confirm: true`)
- Count machines grouped by state and app; list machines for one app
- Fetch and summarize app logs; query Fly Prometheus metrics
- Run custom GraphQL queries

## Prerequisites / setup

**API token** (secret-backed). There is no Fly OAuth integration. Do not open
`/connect/oauth` for Fly. Never paste the token into chat.
Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke, and mutation guards.

| Secret | Purpose |
| --- | --- |
| `flyApiToken` | Fly API token (`flyctl tokens create` or dashboard Access Tokens) |

1. Create a token at [fly.io/dashboard](https://fly.io/dashboard) → Account →
   Access Tokens. A read token is enough for apps, Machines, logs, and metrics.
   Start/stop/destroy need a token that can mutate Machines.
2. Save it in Kody:

https://kody.codes/account/secrets/new?name=flyApiToken&description=Fly.io%20API%20token%20for%20Machines%2C%20GraphQL%2C%20logs%2C%20and%20Prometheus&allowedHosts=api.machines.dev,api.fly.io&scope=user

3. Approve hosts **`api.machines.dev`** and **`api.fly.io`**.

### Hosts

- `api.machines.dev` — Machines REST (apps, Machines, token info, mutations)
- `api.fly.io` — GraphQL, app logs, Prometheus

### Multi-account

Pass `account: "work"` to use secret `flyApiToken-work`. Or pass
`secretName: "flyApiToken-staging"`.

https://kody.codes/account/secrets/new?name=flyApiToken-work&description=Fly.io%20API%20token%20for%20the%20work%20account&allowedHosts=api.machines.dev,api.fly.io&scope=user

When `organizationSlug` is omitted, the package lists organizations visible to
the token: one org is used automatically; multiple orgs require an explicit slug.

## Jobs

The `machine-status` job is declared **disabled**. It is a no-argument wrapper
around `scheduled-status` (read-only machine counts). Enable it only after you
confirm the token, hosts, and organization slug you want it to use.

## Done when

- `flyApiToken` is saved; hosts `api.machines.dev` and `api.fly.io` are approved
- Smoke test returns `{ ok: true }` (`live: false` before credentials; org/apps sample when the secret exists — no writes)
- Machine destroy refuses unless `confirm: true`; `dryRun: true` never contacts Fly

## Branding

`community-icon.svg` is Fly.io's official brandmark (Simple Icons `flydotio`,
approved by Fly.io, CC0) on Fly navy `#24175B`. Fly.io® is a trademark of
Fly.io, Inc. This package is not affiliated with or endorsed by Fly.io.

Keep `LICENSE` (MIT), `## Intent`, and `community-icon.svg` intact for community listing.

## Docs

- [Machines API](https://fly.io/docs/machines/api/)
- [OpenAPI spec](https://docs.machines.dev/spec/openapi3.json)
- [Access tokens](https://fly.io/docs/security/tokens/)