# Fly.io on boxd

> Fly.io transforms containers into micro-VMs that run on hardware in 30+ regions on six continents.

- Page: https://boxd.sh/integrations/fly/
- CLI: `run fly` (45 commands, 13 marked common)
- SDK: `import { fly } from "@boxd/run"`; every parameter and response type is at `@boxd/run/fly`
- Triggers: none
- Connect: `run auth fly` (API key), or https://app.boxd.sh/integrations/detail/fly
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth fly      # once: prints a link to connect your account
run fly           # list its commands
run fly get-regions
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, fly } from "@boxd/run";

every("1 hour", async () => {
  const result = await fly.getRegions({});
  console.log(result);
});
```

Run it with `run fly.run.ts`. Fly.io has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run fly <command> --help` lists the optional ones. "common" marks what `run fly` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-wire-guard-peer` | `fly.addWireGuardPeer()` | `--name` `--organization-id` `--pubkey` | 2 | Add a WireGuard peer connection to a Fly.io organization for private network access |
| `check-app-name-availability` | `fly.checkAppNameAvailability()` | `--name` | 0 | Validate an app name for Fly.io app creation |
| `check-jobs` | `fly.checkJobs()` | `--query` | 1 | Execute GraphQL queries against the Fly.io checkJobs endpoint |
| `check-user-only-token` | `fly.checkUserOnlyToken()` | — | 0 | Check whether the authentication token only allows user access |
| `create-check-job` | `fly.createCheckJob()` | `--http-options` `--locations` `--organization-id` `--url` | 0 | Create a health check job for monitoring application endpoints in Fly.io |
| `create-check-job-run` | `fly.createCheckJobRun()` | `--check-job-id` | 0 | Triggers a run of an existing health check job on Fly.io |
| `create-delegated-wire-guard-token` | `fly.createDelegatedWireGuardToken()` | `--organization-id` | 2 | Create a delegated WireGuard token for peer management in a Fly.io organization |
| `create-third-party-configuration` | `fly.createThirdPartyConfiguration()` | `--customLevel` `--flyctlLevel` `--location` `--name` `--organizationId` `--uiexLevel` | 2 | Create a third-party service configuration for discharging macaroon caveats |
| `delete-delegated-wire-guard-token` | `fly.deleteDelegatedWireGuardToken()` | `--organization-id` | 3 | Delete a delegated WireGuard token from a Fly.io organization |
| `delete-organization` | `fly.deleteOrganization()` | `--organizationId` | 1 | Delete a Fly.io organization and all its associated resources using the GraphQL API |
| `delete-remote-builder` | `fly.deleteRemoteBuilder()` | `--organization-id` | 1 | Delete a remote builder configuration for a Fly.io organization |
| `delete-third-party-configuration` | `fly.deleteThirdPartyConfiguration()` | `--third-party-configuration-id` | 1 | Delete a third-party service configuration from Fly.io |
| `detach-postgres-cluster` | `fly.detachPostgresCluster()` | `--app-id` `--postgres-cluster-app-id` | 2 | Detach a Postgres cluster from a Fly.io application, revoking access credentials |
| `establish-ssh-key` | `fly.establishSshKey()` | `--organization-id` | 2 | Establish an SSH key for a Fly.io organization |
| `fetch-nodes-by-ids` | `fly.fetchNodesByIds()` | `--ids` | 1 | Fetches a list of node objects from Fly.io given a list of IDs using the GraphQL nodes query |
| `get-add-on` | `fly.getAddOn()` | — | 3 | Find a Fly.io add-on by ID, name, or provider |
| `get-add-on-provider` | `fly.getAddOnProvider()` | `--name` | 0 | Query information about a specific Fly.io add-on provider (extension) by name |
| `get-app-details` ·common | `fly.getAppDetails()` | `--name` | 0 | Retrieve detailed information about a specific Fly.io application |
| `get-certificate` | `fly.getCertificate()` | `--certificate-id` | 0 | Retrieve a certificate by its ID from Fly.io |
| `get-current-token-info` ·common | `fly.getCurrentTokenInfo()` | — | 0 | Get information about the current authentication token |
| `get-latest-image-details` | `fly.getLatestImageDetails()` | `--image` | 1 | Retrieve the latest available tag details for a given image repository from Fly.io's registry |
| `get-latest-image-tag` | `fly.getLatestImageTag()` | `--repository` | 0 | Retrieve the latest available image tag for a Fly.io Docker repository |
| `get-machine` ·common | `fly.getMachine()` | `--machineId` | 0 | Get a single machine by ID from Fly.io |
| `get-nearest-region` | `fly.getNearestRegion()` | — | 0 | Retrieve the nearest Fly.io region to the requesting client based on network location |
| `get-node` | `fly.getNode()` | `--id` | 0 | Fetch an object by its globally unique ID using Fly.io's GraphQL node query |
| `get-organization` ·common | `fly.getOrganization()` | `--slug` | 0 | Find a Fly.io organization by slug using the GraphQL API |
| `get-personal-organization` ·common | `fly.getPersonalOrganization()` | — | 0 | Retrieve the user's personal organization details from Fly.io |
| `get-placements` ·common | `fly.getPlacements()` | `--org-slug` | 6 | Get placement recommendations for Machines in Fly.io regions |
| `get-platform-info` ·common | `fly.getPlatformInfo()` | — | 0 | Retrieve Fly.io platform information including available regions, VM sizes, and flyctl version |
| `get-products` | `fly.getProducts()` | — | 0 | Retrieve Fly.io product and price information via GraphQL |
| `get-regions` ·common | `fly.getRegions()` | — | 6 | Get the list of available Fly.io regions with optional filtering |
| `get-viewer-info` ·common | `fly.getViewerInfo()` | — | 1 | Retrieve the authenticated user's account information from Fly.io |
| `issue-certificate` | `fly.issueCertificate()` | `--organization-id` | 5 | Issue an SSH certificate for accessing Fly.io infrastructure |
| `list-add-on-plans` | `fly.listAddOnPlans()` | — | 4 | List available add-on service plans from Fly.io |
| `list-add-ons` | `fly.listAddOns()` | — | 2 | List add-ons associated with an organization in Fly.io |
| `list-apps` ·common | `fly.listApps()` | `--org-slug` | 1 | List all Fly Apps in an organization |
| `list-apps-graphql` ·common | `fly.listAppsGraphql()` | — | 7 | List all Fly.io applications with details including volumes, services, and VMs using GraphQL |
| `list-check-locations` | `fly.listCheckLocations()` | — | 0 | Retrieve all available Fly.io health check locations |
| `list-machines` ·common | `fly.listMachines()` | — | 4 | List Fly.io machines using GraphQL API with pagination support |
| `list-org-machines` ·common | `fly.listOrgMachines()` | `--org-slug` | 6 | List all Machines across all apps in a Fly organization |
| `remove-wire-guard-peer` | `fly.removeWireGuardPeer()` | `--name` `--organization-id` | 0 | Remove a WireGuard peer connection from a Fly.io organization |
| `set-apps-v2-default-on` | `fly.setAppsV2DefaultOn()` | `--default-on` `--organization-slug` | 0 | Configure whether new apps in an organization use Apps V2 by default on Fly.io |
| `update-third-party-configuration` | `fly.updateThirdPartyConfiguration()` | `--thirdPartyConfigurationId` | 7 | Update an existing third-party service configuration for discharging macaroon caveats |
| `validate-config` | `fly.validateConfig()` | `--definition` | 0 | Validate a Fly.io app configuration |
| `validate-wire-guard-peers` | `fly.validateWireGuardPeers()` | `--peer-ips` | 0 | Validate WireGuard peer IP addresses in a Fly.io organization |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.