### Install flyctl using Install Script (Pre-release)

Source: https://github.com/superfly/flyctl/blob/master/README.md

Downloads and installs the latest pre-release version of flyctl using the official install script. Use this for testing upcoming features on MacOS, Linux, and WSL.

```bash
curl -L https://fly.io/install.sh | sh -s pre
```

--------------------------------

### Start SFTP Shell

Source: https://context7.com/superfly/flyctl/llms.txt

Initiates an SFTP shell session for uploading or downloading files to/from a remote machine. Use `put` and `get` commands within the shell.

```bash
fly ssh sftp shell -a my-app
```

--------------------------------

### fly.toml Configuration Example

Source: https://context7.com/superfly/flyctl/llms.txt

A full example of a fly.toml file, illustrating various configuration options for an application, including build settings, deployment strategies, environment variables, VM specifications, HTTP service configuration, mounts, restart policies, and health checks.

```toml
app            = "my-app"
primary_region = "ord"
kill_signal    = "SIGTERM"
kill_timeout   = "5s"
swap_size_mb   = 512

[build]
  dockerfile  = "Dockerfile"
  build-target = "production"
  [build.args]
    RAILS_ENV = "production"

[deploy]
  strategy               = "rolling"
  release_command        = "bundle exec rails db:migrate"
  release_command_timeout = "5m"
  max_unavailable        = 0.34

[env]
  PORT = "8080"
  LOG_LEVEL = "info"

[[vm]]
  size   = "shared-cpu-2x"
  memory = "1gb"

[http_service]
  internal_port       = 8080
  force_https         = true
  auto_stop_machines  = true
  auto_start_machines = true
  min_machines_running = 0

  [http_service.concurrency]
    type       = "requests"
    soft_limit = 200
    hard_limit = 250

[[mounts]]
  source      = "myapp_data"
  destination = "/data"
  initial_size = "10gb"
  auto_extend_size_threshold = 80
  auto_extend_size_increment = "5gb"
  auto_extend_size_limit     = "50gb"

[[restart]]
  policy      = "on-failure"
  retries     = 3

[metrics]
  port = 9091
  path = "/metrics"

[[checks]]
  [checks.alive]
    grace_period = "5s"
    interval     = "15s"
    method       = "GET"
    path         = "/health"
    protocol     = "http"
    timeout      = "2s"

```

--------------------------------

### Example fly.toml configuration

Source: https://github.com/superfly/flyctl/blob/master/README.md

A minimal example of a fly.toml configuration file. flyctl uses this file to determine the application name and other settings when operating in a directory.

```bash
app: banana
```

--------------------------------

### Start Wintun Session

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Starts a tunnel session on a given Wintun adapter. The `capacity` parameter specifies the ring buffer size. A capacity of 0x400000 is used in this example.

```C
WINTUN_SESSION_HANDLE Session = WintunStartSession(Adapter2, 0x400000);
```

--------------------------------

### Install flyctl using Install Script (Latest)

Source: https://github.com/superfly/flyctl/blob/master/README.md

Downloads and installs the latest stable version of flyctl using the official install script. This is suitable for MacOS, Linux, and WSL.

```bash
curl -L https://fly.io/install.sh | sh
```

--------------------------------

### Install flyctl using Install Script (Specific Version)

Source: https://github.com/superfly/flyctl/blob/master/README.md

Downloads and installs a specific version of flyctl using the official install script. Replace '0.0.200' with the desired version number for MacOS, Linux, and WSL.

```bash
curl -L https://fly.io/install.sh | sh -s 0.0.200
```

--------------------------------

### WintunStartSession

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Starts a Wintun session for a given adapter with a specified ring capacity.

```APIDOC
## WintunStartSession()

### Description
Starts a Wintun session. The session handle must be released with WintunEndSession.

### Parameters
#### Path Parameters
- **Adapter** (WINTUN_ADAPTER_HANDLE) - Required - Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter.
- **Capacity** (DWORD) - Required - Rings capacity. Must be between WINTUN_MIN_RING_CAPACITY and WINTUN_MAX_RING_CAPACITY (inclusive) and must be a power of two.

### Returns
- A Wintun session handle if the function succeeds.
- NULL if the function fails. Call GetLastError for extended error information.
```

--------------------------------

### Install flyctl with Homebrew

Source: https://github.com/superfly/flyctl/blob/master/README.md

Installs the flyctl CLI using the Homebrew package manager on macOS, Linux, or WSL. Ensure Homebrew is installed first.

```bash
brew install flyctl
```

--------------------------------

### Configure Preflight Integration Tests

Source: https://github.com/superfly/flyctl/blob/master/CONTRIBUTING.md

Set up environment variables for preflight integration tests by copying the example file and modifying specific variables. Use a dedicated organization for testing and specify desired regions.

```bash
cp .direnv/preflight-example .direnv/preflight
export FLY_PREFLIGHT_TEST_FLY_ORG=<your_test_org>
export FLY_PREFLIGHT_TEST_FLY_REGIONS="iad sin"
export FLY_PREFLIGHT_TEST_ACCESS_TOKEN=$(fly auth token)
```

--------------------------------

### Install flyctl on Windows with PowerShell

Source: https://github.com/superfly/flyctl/blob/master/README.md

Installs flyctl on Windows by running the official Powershell install script. This command should be executed in a Powershell terminal.

```powershell
iwr https://fly.io/install.ps1 -useb | iex
```

--------------------------------

### Create Wintun Adapters

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Creates Wintun adapters within a specified pool. Each adapter can have a unique name and GUID. Ensure GUIDs are unique for each adapter.

```C
WINTUN_ADAPTER_HANDLE Adapter1 = WintunCreateAdapter(L"WireGuard", L"OfficeNet", &SomeFixedGUID1, NULL);
WINTUN_ADAPTER_HANDLE Adapter2 = WintunCreateAdapter(L"WireGuard", L"HomeNet", &SomeFixedGUID2, NULL);
WINTUN_ADAPTER_HANDLE Adapter3 = WintunCreateAdapter(L"WireGuard", L"Data Center", &SomeFixedGUID3, NULL);
```

--------------------------------

### Install flyctl via Package Manager or Script

Source: https://context7.com/superfly/flyctl/llms.txt

Install or upgrade flyctl using Homebrew, a shell script, or PowerShell. The install script can be used for specific versions.

```bash
# macOS / Linux / WSL — Homebrew
brew install flyctl
```

```bash
# macOS / Linux / WSL — install script (latest)
curl -L https://fly.io/install.sh | sh
```

```bash
# macOS / Linux / WSL — specific version
curl -L https://fly.io/install.sh | sh -s 0.0.200
```

```powershell
# Windows — PowerShell
iwr https://fly.io/install.ps1 -useb | iex
```

```bash
# Upgrade via Homebrew
brew upgrade flyctl
```

--------------------------------

### Start MCP Server Process

Source: https://context7.com/superfly/flyctl/llms.txt

Launches an MCP (Model Context Protocol) server process locally. This is typically used for AI-assisted tooling.

```bash
fly mcp server
```

--------------------------------

### Start WireGuard Agent

Source: https://context7.com/superfly/flyctl/llms.txt

Launches the built-in WireGuard agent, which manages peer connections and network routing for private access.

```bash
fly agent start
```

--------------------------------

### Log in to fly.io account

Source: https://github.com/superfly/flyctl/blob/master/README.md

Authenticates your flyctl CLI with your fly.io account. This is typically the first step after installation.

```bash
fly auth login
```

--------------------------------

### fly machine Commands

Source: https://context7.com/superfly/flyctl/llms.txt

Low-level commands for managing individual Fly Machines. Use `fly machine run` to start a new machine from an image with specified configurations, `fly machine list` to view existing machines, and `fly machine status` to check a machine's state. Commands like `start`, `stop`, `restart`, and `kill` control machine lifecycle. `fly machine update` can change an image or config, `clone` creates a copy in another region, and `exec` runs a command on a running machine. Machines can be destroyed with `destroy`, suspended with `suspend`, removed from load balancing with `cordon`, or added back with `uncordon`. `fly machine wait` pauses execution until a machine reaches a specified state.

```bash
# Run a one-off machine from an image
fly machine run registry.fly.io/my-app:latest \
  --region ord \
  --vm-size shared-cpu-2x \
  --env KEY=value \
  --port 8080/tcp:http:tls \
  --volume mydata:/data
```

```bash
# List machines for an app
fly machine list -a my-app
```

```bash
# Show machine status
fly machine status <machine-id>
```

```bash
# Start / stop / restart / kill
fly machine start  <machine-id>
fly machine stop   <machine-id>
fly machine restart <machine-id>
fly machine kill   <machine-id>
```

```bash
# Update a machine's image or config
fly machine update <machine-id> --image registry.fly.io/my-app:v43
```

```bash
# Clone a machine to a different region
fly machine clone <machine-id> --region lax
```

```bash
# Execute a command on a running machine
fly machine exec <machine-id> -- /bin/sh -c "printenv"
```

```bash
# Destroy a machine
fly machine destroy <machine-id> --force
```

```bash
# Suspend / cordon (remove from load-balancer) / uncordon
fly machine suspend  <machine-id>
fly machine cordon   <machine-id>
fly machine uncordon <machine-id>
```

```bash
# Wait for a machine to reach a given state
fly machine wait <machine-id> --state started
```

--------------------------------

### Upgrade flyctl with Homebrew

Source: https://github.com/superfly/flyctl/blob/master/README.md

Upgrades an existing flyctl installation to the latest version using Homebrew.

```bash
brew upgrade flyctl
```

--------------------------------

### WintunStartSession

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Starts a tunnel session on a Wintun adapter. This function is used to begin sending and receiving packets.

```APIDOC
## WintunStartSession

### Description
Starts a tunnel session on a Wintun adapter. This is necessary before sending or receiving packets.

### Function Signature
`WINTUN_SESSION_HANDLE WintunStartSession(WINTUN_ADAPTER_HANDLE Adapter, DWORD Capacity)`

### Parameters

*   **Adapter** (WINTUN_ADAPTER_HANDLE) - The handle to the Wintun adapter.
*   **Capacity** (DWORD) - The desired capacity of the ring buffer for the session (e.g., 0x400000 for 4MiB).

### Return Value
A handle to the Wintun session, or NULL if the session cannot be started.
```

--------------------------------

### WintunGetReadWaitEvent

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Gets the event handle for waiting on data availability within a Wintun session.

```APIDOC
## WintunGetReadWaitEvent()

### Description
Gets the Wintun session's read-wait event handle. This event can be used to wait for available data when reading. If WintunReceivePackets returns ERROR_NO_MORE_ITEMS, waiting on this event before retrying is recommended.

### Parameters
#### Path Parameters
- **Session** (WINTUN_SESSION_HANDLE) - Required - Wintun session handle obtained with WintunStartSession.

### Returns
- A HANDLE to the event. Do not call CloseHandle on this event as it is managed by the session.
```

--------------------------------

### Filter Failing Health Checks

Source: https://context7.com/superfly/flyctl/llms.txt

Outputs health check results in JSON format and filters them to show only those that are not passing. Requires `jq` to be installed.

```bash
fly checks list -a my-app --json | jq '.[] | select(.status != "passing")'
```

--------------------------------

### Launch a New App with `fly launch`

Source: https://context7.com/superfly/flyctl/llms.txt

Scan the current directory, detect framework/language, generate `fly.toml`, provision databases, and optionally deploy. Supports pre-built images.

```bash
# Interactive launch in current directory
fly launch
```

```bash
# Non-interactive: supply all options up front
fly launch \
  --name my-rails-app \
  --region ord \
  --org personal \
  --vm-size shared-cpu-2x \
  --ha \
  --no-deploy
```

```bash
# Launch from a pre-built image
fly launch --image registry.fly.io/my-image:latest --no-deploy
```

```bash
# Launch and attach a Postgres cluster
fly launch --name my-app --region lax
# (answer "yes" to the Postgres prompt during interactive flow)
```

--------------------------------

### Run flyctl

Source: https://github.com/superfly/flyctl/blob/master/CONTRIBUTING.md

Execute the built flyctl binary or run it directly using 'go run'. Running with 'go run' has a slower startup time.

```bash
./bin/flyctl
```

```bash
go run . m update -a <app_name> <machine_id>
```

```bash
go run .
```

--------------------------------

### Build flyctl from Source

Source: https://context7.com/superfly/flyctl/llms.txt

Follow these steps to clone the flyctl repository and build the binary from source. This includes setting up prerequisites and running development tasks like tests and documentation generation.

```bash
# Prerequisites: Go 1.22+, make
git clone https://github.com/superfly/flyctl.git
cd flyctl

# Build binary to ./bin/fly
make build

# Run tests
go test ./...

# Regenerate GraphQL client from schema
go generate ./gql/...

# Generate CLI help docs
go run ./doc
```

--------------------------------

### Run golangci-lint

Source: https://github.com/superfly/flyctl/blob/master/CONTRIBUTING.md

Execute the golangci-lint linter locally to find potential bugs and ensure adherence to Go conventions. Use --path-prefix=. to run it for the current project.

```bash
golangci-lint --path-prefix=. run
```

--------------------------------

### Build flyctl

Source: https://github.com/superfly/flyctl/blob/master/CONTRIBUTING.md

Build the flyctl binary using make or go build. The binary will be placed in the bin/ directory.

```bash
make build
```

```bash
go build -o <EXE_NAME> .
```

--------------------------------

### Show Postgres Configuration

Source: https://context7.com/superfly/flyctl/llms.txt

Retrieves and displays the current configuration settings for a Postgres cluster.

```bash
fly postgres config show -a my-pg
```

--------------------------------

### List All Tokens for an App

Source: https://context7.com/superfly/flyctl/llms.txt

Retrieves a list of all access and deploy tokens associated with a particular application.

```bash
fly tokens list -a my-app
```

--------------------------------

### Manage Applications with `fly apps`

Source: https://context7.com/superfly/flyctl/llms.txt

Create, list, inspect, suspend, resume, restart, move, and destroy applications on the Fly.io platform. Use `--save` to update `fly.toml`.

```bash
# Create a new app (interactive name prompt)
fly apps create
```

```bash
# Create with explicit name and org, save name to fly.toml
fly apps create my-app --org my-org --save
```

```bash
# Create with auto-generated name, JSON output
fly apps create --generate-name --json
```

```bash
# List all apps
fly apps list
```

```bash
# Open app in browser
fly apps open -a my-app
```

```bash
# List releases for an app
fly apps releases -a my-app
```

```bash
# Suspend / resume / restart
fly apps suspend -a my-app
fly apps resume  -a my-app
fly apps restart -a my-app
```

```bash
# Move app to different org
fly apps move my-app --org other-org
```

```bash
# Destroy app (no confirmation prompt)
fly apps destroy my-app --yes
```

--------------------------------

### Deploy Applications with `fly deploy`

Source: https://context7.com/superfly/flyctl/llms.txt

Build and deploy images using various strategies (rolling, bluegreen, immediate). Supports Docker, Nixpacks, Buildpacks, or pre-built images. Use `--detach` for detached mode.

```bash
# Standard rolling deploy from current directory
fly deploy
```

```bash
# Deploy a specific image (skips build)
fly deploy --image registry.fly.io/my-app:v42
```

```bash
# Blue-green deployment with SIGINT for graceful stop
fly deploy --strategy bluegreen --signal SIGINT
```

```bash
# Immediate deploy (update all machines in parallel), cap concurrency
fly deploy --strategy immediate --max-concurrent 4
```

```bash
# Deploy with custom Dockerfile and build arg
fly deploy \
  --dockerfile ./docker/Dockerfile.prod \
  --build-arg RAILS_ENV=production \
  --wait-timeout 5m
```

```bash
# Deploy only to specific regions or machines
fly deploy --regions ord,iad
fly deploy --only-machines 3d8d9191c4e183,ab12cd34ef56gh
```

```bash
# Build remotely (no local Docker daemon required)
fly deploy --remote-only
```

```bash
# Build using depot.dev
fly deploy --depot
```

```bash
# Deploy and don't wait (detached mode)
fly deploy --detach
```

```bash
# Skip smoke checks or DNS checks
fly deploy --no-smoke-checks --no-dns-checks
```

--------------------------------

### List fly.io applications

Source: https://github.com/superfly/flyctl/blob/master/README.md

Displays a list of all applications associated with your fly.io account. This command helps in managing your deployed services.

```bash
fly apps list
```

--------------------------------

### Run Preflight Integration Tests

Source: https://github.com/superfly/flyctl/blob/master/CONTRIBUTING.md

Execute preflight integration tests using 'make preflight-test'. To run a specific test, use the T=<test_name> argument.

```bash
make preflight-test
```

```bash
make preflight-test T=<test_name>
```

--------------------------------

### List All IPs for an App

Source: https://context7.com/superfly/flyctl/llms.txt

Displays all public and private IP addresses currently allocated to a specific application.

```bash
fly ips list -a my-app
```

--------------------------------

### Create New WireGuard Peer Configuration

Source: https://context7.com/superfly/flyctl/llms.txt

Generates a new WireGuard peer configuration file, including necessary keys and endpoint details, for establishing private network connections.

```bash
fly wireguard create my-org iad my-peer wg0.conf
```

--------------------------------

### WintunCreateAdapter

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Creates a Wintun adapter. Adapters have names and belong to a pool. Multiple tunnels can be created within the same pool.

```APIDOC
## WintunCreateAdapter

### Description
Creates a Wintun adapter. Adapters have names (e.g., "OfficeNet") and belong to a pool (e.g., "WireGuard").

### Function Signature
`WINTUN_ADAPTER_HANDLE WintunCreateAdapter(LPCWSTR Tunnel, LPCWSTR Name, const GUID *Instance, void *Reserved)`

### Parameters

*   **Tunnel** (LPCWSTR) - The name of the pool the adapter belongs to.
*   **Name** (LPCWSTR) - The name of the adapter.
*   **Instance** (const GUID *) - A unique GUID for the adapter instance.
*   **Reserved** (void *) - Reserved for future use.

### Return Value
A handle to the created Wintun adapter, or NULL if creation fails.
```

--------------------------------

### List MCP Server Apps

Source: https://context7.com/superfly/flyctl/llms.txt

Displays a list of all MCP server applications currently deployed on Fly.io.

```bash
fly mcp list
```

--------------------------------

### Cut a Release

Source: https://github.com/superfly/flyctl/blob/master/CONTRIBUTING.md

Ship a prerelease or a full release using the bump_version.sh script. Requires write access to the repository.

```bash
scripts/bump_version.sh prerel
```

```bash
scripts/bump_version.sh
```

--------------------------------

### Run all pre-commit lints

Source: https://github.com/superfly/flyctl/blob/master/CONTRIBUTING.md

Execute all pre-commit hooks to ensure code quality and consistency across the project.

```bash
pre-commit run --all-files
```

--------------------------------

### Stream Live Application Logs

Source: https://context7.com/superfly/flyctl/llms.txt

Continuously streams application logs from all machines in an app. Press Ctrl-C to stop.

```bash
fly logs -a my-app
```

--------------------------------

### WintunCreateAdapter

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Creates a new Wintun network adapter. This function allocates resources for a new virtual network adapter that can be used by the system. The adapter handle must be released using WintunFreeAdapter.

```APIDOC
## WintunCreateAdapter

### Description
Creates a new Wintun adapter.

### Parameters
- **Pool** (const WCHAR *) - Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
- **Name** (const WCHAR *) - The requested name of the adapter. Zero-terminated string of up to MAX_ADAPTER_NAME-1 characters.
- **RequestedGUID** (const GUID *) - The GUID of the created network adapter. If NULL, the GUID is chosen randomly by the system.
- **RebootRequired** (BOOL *) - Optional pointer to a boolean flag set to TRUE if SetupAPI suggests a reboot.

### Returns
- **WINTUN_ADAPTER_HANDLE**: On success, a handle to the created adapter. Must be released with WintunFreeAdapter.
- **NULL**: On failure. Call GetLastError for extended error information.
```

--------------------------------

### Show All Machines Status (Including Stopped)

Source: https://context7.com/superfly/flyctl/llms.txt

Displays the status of an application, including all machines, even those that are currently stopped.

```bash
fly status -a my-app --all
```

--------------------------------

### WintunOpenAdapter

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Opens an existing Wintun adapter. This function retrieves a handle to an already created Wintun adapter, allowing for its use. The adapter handle must be released using WintunFreeAdapter.

```APIDOC
## WintunOpenAdapter

### Description
Opens an existing Wintun adapter.

### Parameters
- **Pool** (const WCHAR *) - Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
- **Name** (const WCHAR *) - Adapter name. Zero-terminated string of up to MAX_ADAPTER_NAME-1 characters.

### Returns
- **WINTUN_ADAPTER_HANDLE**: On success, a handle to the opened adapter. Must be released with WintunFreeAdapter.
- **NULL**: On failure. Call GetLastError for extended error information. Possible errors include ERROR_FILE_NOT_FOUND or ERROR_ALREADY_EXISTS.
```

--------------------------------

### Fly.io Configuration File

Source: https://context7.com/superfly/flyctl/llms.txt

The `~/.fly/config.yml` file stores authentication tokens and other configuration settings, typically written by `fly auth login`.

```yaml
# ~/.fly/config.yml — written by `fly auth login`
access_token: fo1_abc123...
wire_guard_state: ...
```

--------------------------------

### Create Deploy Token

Source: https://context7.com/superfly/flyctl/llms.txt

Generates a deploy token for an application, typically used for CI/CD pipelines to authenticate deployments.

```bash
fly tokens create deploy -a my-app
```

--------------------------------

### Connect to Machine via SSH Interactively

Source: https://context7.com/superfly/flyctl/llms.txt

Opens an interactive SSH console to a selected machine within an application. Use `--select` to choose from available machines.

```bash
fly ssh console -a my-app --select
```

--------------------------------

### WINTUN_MIN_RING_CAPACITY Macro

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Defines the minimum ring capacity for Wintun, set to 128kiB.

```C
#define WINTUN_MIN_RING_CAPACITY   0x20000 /* 128kiB */
```

--------------------------------

### List Users in Postgres Cluster

Source: https://context7.com/superfly/flyctl/llms.txt

Displays a list of all users configured for the specified Postgres cluster.

```bash
fly postgres users list -a my-pg
```

--------------------------------

### Connect to Machine via SSH as Specific User

Source: https://context7.com/superfly/flyctl/llms.txt

Establishes an SSH connection to a machine, specifying the user to connect as. Useful for deployment or service accounts.

```bash
fly ssh console -a my-app --user deploy
```

--------------------------------

### fly config Commands

Source: https://context7.com/superfly/flyctl/llms.txt

Commands for managing application configuration. Use `fly config show` to see the parsed configuration from fly.toml, `fly config env` to view environment variables, and `fly config validate` to check the validity of your fly.toml file. `fly config save` can be used to fetch remote configuration back to a local file.

```bash
# Show current config (parsed from fly.toml)
fly config show
```

```bash
# Show env section only
fly config env
```

```bash
# Validate fly.toml against the platform
fly config validate
```

```bash
# Strict validation (flags unrecognised keys)
fly config validate --strict
```

```bash
# Save remote app config back to fly.toml
fly config save -a my-app
```

--------------------------------

### Launch Persistent MCP Server App

Source: https://context7.com/superfly/flyctl/llms.txt

Deploys an MCP server as a persistent application on Fly.io, specifying its name, organization, and region.

```bash
fly mcp launch --name my-mcp --org my-org --region ord
```

--------------------------------

### Connect to Postgres Cluster

Source: https://context7.com/superfly/flyctl/llms.txt

Establishes an interactive `psql` session via a proxy to the specified Postgres cluster.

```bash
fly postgres connect -a my-pg
```

--------------------------------

### Check Local Environment Diagnostics

Source: https://context7.com/superfly/flyctl/llms.txt

Runs diagnostic checks on the local environment, including WireGuard, Docker, and authentication status, to identify potential issues.

```bash
fly doctor
```

--------------------------------

### Create New Postgres Cluster

Source: https://context7.com/superfly/flyctl/llms.txt

Provisions a new High-Availability Postgres cluster with specified configurations for name, region, VM size, cluster size, volume size, and backup enablement.

```bash
fly postgres create \
  --name my-pg \
  --region ord \
  --vm-size shared-cpu-2x \
  --initial-cluster-size 2 \
  --volume-size 10 \
  --enable-backups
```

--------------------------------

### Check Specific App Configuration and Connectivity

Source: https://context7.com/superfly/flyctl/llms.txt

Performs diagnostic checks on a specific application's configuration and network connectivity to ensure it's running correctly on Fly.io.

```bash
fly doctor -a my-app
```

--------------------------------

### Run Unit Tests

Source: https://github.com/superfly/flyctl/blob/master/CONTRIBUTING.md

Execute all unit tests for the flyctl project. Unit tests are located next to the functionality they are testing.

```bash
make test
```

--------------------------------

### WintunEnumAdapters

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Enumerates all Wintun adapters within a specified pool. This function iterates through available Wintun adapters and invokes a callback function for each one found.

```APIDOC
## WintunEnumAdapters

### Description
Enumerates all Wintun adapters.

### Parameters
- **Pool** (const WCHAR *) - Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
- **Callback** (WINTUN_ENUM_CALLBACK) - Callback function to be invoked for each adapter. Return TRUE to continue enumeration, FALSE to stop.
- **Param** (LPARAM) - Application-defined value passed to the callback function.

### Returns
- **nonzero (BOOL)**: If the function succeeds.
- **zero (BOOL)**: If the function fails. Call GetLastError for extended error information.
```

--------------------------------

### View application status

Source: https://github.com/superfly/flyctl/blob/master/README.md

Shows the current status and details of a specific application deployed on fly.io. Replace '{app-name}' with the actual name of your application.

```bash
fly status -a {app-name}
```

--------------------------------

### WINTUN_MAX_RING_CAPACITY Macro

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Defines the maximum ring capacity for Wintun, set to 64MiB.

```C
#define WINTUN_MAX_RING_CAPACITY   0x4000000 /* 64MiB */
```

--------------------------------

### Send Diagnostic Report to Fly Support

Source: https://context7.com/superfly/flyctl/llms.txt

Generates and sends a comprehensive diagnostic report of the local environment and app configuration to Fly.io support for assistance.

```bash
fly doctor diag
```

--------------------------------

### Output Application Status as JSON

Source: https://context7.com/superfly/flyctl/llms.txt

Retrieves the application status information formatted as JSON, suitable for programmatic processing.

```bash
fly status -a my-app --json
```

--------------------------------

### Create WireGuard Token

Source: https://context7.com/superfly/flyctl/llms.txt

Generates a WireGuard token, which is required for setting up new peers and establishing secure connections.

```bash
fly wireguard token create my-org
```

--------------------------------

### Authenticate with Fly.io Platform

Source: https://context7.com/superfly/flyctl/llms.txt

Log in to the Fly platform using browser-based, interactive email/password, or token-based flows. Useful for CI/CD pipelines.

```bash
# Browser-based login (default)
fly auth login
```

```bash
# Interactive email/password login
fly auth login --interactive --email user@example.com --password secret --otp 123456
```

```bash
# Print current auth token (useful for CI)
fly auth token
```

```bash
# Show authenticated user
fly auth whoami
```

```bash
# Log out
fly auth logout
```

```bash
# Authenticate Docker with Fly's registry
fly auth docker
```

--------------------------------

### fly volumes Commands

Source: https://context7.com/superfly/flyctl/llms.txt

Commands for managing persistent block storage volumes. Use `fly volumes create` to provision a new volume with specified size and snapshot retention, `fly volumes list` to see all volumes, and `fly volumes show` for details. Volumes can be extended with `fly volumes extend`, cloned with `fly volumes fork`, and snapshot retention updated with `fly volumes update`. Volumes can be permanently removed using `fly volumes destroy`.

```bash
# Create a 10 GB volume in the ord region
fly volumes create myapp_data \
  --app my-app \
  --region ord \
  --size 10 \
  --snapshot-retention 7
```

```bash
# List volumes
fly volumes list -a my-app
```

```bash
# Show volume details
fly volumes show <volume-id>
```

```bash
# Extend a volume to 20 GB
fly volumes extend <volume-id> --size 20
```

```bash
# Fork (clone) a volume
fly volumes fork <volume-id> --region iad
```

```bash
# Update snapshot retention
fly volumes update <volume-id> --snapshot-retention 14
```

```bash
# Destroy a volume
fly volumes destroy <volume-id> --yes
```

--------------------------------

### Verify flyctl Authentication

Source: https://context7.com/superfly/flyctl/llms.txt

Use the `fly auth whoami` command to verify your current authentication token and identity, especially in automated environments like CI.

```bash
fly auth whoami
```

--------------------------------

### List Databases in Postgres Cluster

Source: https://context7.com/superfly/flyctl/llms.txt

Retrieves a list of all databases available within the specified Postgres cluster.

```bash
fly postgres db list -a my-pg
```

--------------------------------

### fly ssh Commands

Source: https://context7.com/superfly/flyctl/llms.txt

Commands for establishing SSH access to Fly Machines. `fly ssh console` opens an interactive shell on any machine in the app or a specific machine if an ID is provided. This access is secured over WireGuard.

```bash
# Open interactive SSH console on any machine in the app
fly ssh console -a my-app
```

```bash
# Connect to a specific machine
fly ssh console -a my-app --machine <machine-id>
```

--------------------------------

### Attach Postgres to Application

Source: https://context7.com/superfly/flyctl/llms.txt

Links a Postgres cluster to an application, automatically setting the `DATABASE_URL` secret for the app.

```bash
fly postgres attach my-pg -a my-app
```

--------------------------------

### fly scale Commands

Source: https://context7.com/superfly/flyctl/llms.txt

Commands for adjusting the scale of an application's Machines. `fly scale count` sets the number of machines, with options to limit per region or by process group. `fly scale show` displays the current scaling configuration. `fly scale vm` changes the VM size for all machines, and `fly scale memory` adjusts memory allocation without altering the CPU size.

```bash
# Scale app to 3 machines in every region
fly scale count 3 -a my-app
```

```bash
# Scale a specific process group, limit per region
fly scale count 5 --process-group worker --max-per-region 2
```

```bash
# Show current scale
fly scale show
```

```bash
# Change VM size for all machines
fly scale vm shared-cpu-4x
```

```bash
# Adjust memory without changing CPU
fly scale memory 2048
```

--------------------------------

### Show Application Status

Source: https://context7.com/superfly/flyctl/llms.txt

Displays the overall status of an application, including details about its machines, health, region, and running image.

```bash
fly status -a my-app
```

--------------------------------

### View MCP Server Logs

Source: https://context7.com/superfly/flyctl/llms.txt

Retrieves and displays the logs generated by an MCP server application running on Fly.io.

```bash
fly mcp logs -a my-mcp
```

--------------------------------

### Output Logs as JSON

Source: https://context7.com/superfly/flyctl/llms.txt

Formats application logs as JSON, facilitating programmatic parsing and analysis.

```bash
fly logs -a my-app --json
```

--------------------------------

### WINTUN_MIN_RING_CAPACITY

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Defines the minimum ring capacity for a Wintun session.

```APIDOC
## WINTUN_MIN_RING_CAPACITY

`#define WINTUN_MIN_RING_CAPACITY   0x20000 /* 128kiB */`

Minimum ring capacity.
```

--------------------------------

### WintunReceivePacket

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Receives a packet from the Wintun adapter. Returns NULL if no packets are available.

```APIDOC
## WintunReceivePacket

### Description
Attempts to receive a packet from the Wintun adapter. If no packets are available, it returns NULL and `GetLastError()` will indicate the reason (e.g., `ERROR_NO_MORE_ITEMS`).

### Function Signature
`BYTE *WintunReceivePacket(WINTUN_SESSION_HANDLE Session, DWORD *PacketSize)`

### Parameters

*   **Session** (WINTUN_SESSION_HANDLE) - The handle to the Wintun session.
*   **PacketSize** (DWORD *) - A pointer to a DWORD that will be filled with the size of the received packet.

### Return Value
A pointer to the received packet data, or NULL if no packet is available. The caller must call `WintunReleaseReceivePacket` to release the buffer.
```

--------------------------------

### WintunSetAdapterName

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Sets the name of a Wintun adapter.

```APIDOC
## WintunSetAdapterName()

### Description
Sets the name of the Wintun adapter.

### Parameters
#### Path Parameters
- **Adapter** (WINTUN_ADAPTER_HANDLE) - Required - Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter.
- **Name** (const WCHAR *) - Required - The desired adapter name. Zero-terminated string of up to MAX_ADAPTER_NAME-1 characters.

### Returns
- Nonzero if the function succeeds.
- Zero if the function fails. Call GetLastError for extended error information.
```

--------------------------------

### Failover Postgres Cluster

Source: https://context7.com/superfly/flyctl/llms.txt

Initiates a failover process for the Postgres cluster, promoting a replica to primary.

```bash
fly postgres failover -a my-pg
```

--------------------------------

### Allocate Public IPv6 Address

Source: https://context7.com/superfly/flyctl/llms.txt

Assigns a public IPv6 address to the application, enabling global connectivity.

```bash
fly ips allocate-v6 -a my-app
```

--------------------------------

### Create Organization-Scoped Token

Source: https://context7.com/superfly/flyctl/llms.txt

Creates an access token scoped to a specific organization, allowing actions within that organization.

```bash
fly tokens create org --org my-org
```

--------------------------------

### Run One-Off Command via SSH

Source: https://context7.com/superfly/flyctl/llms.txt

Execute a command non-interactively on a remote machine using SSH. Useful for tasks like database migrations.

```bash
fly ssh console -a my-app -C "bundle exec rails db:migrate"
```

--------------------------------

### Generate GraphQL Schema

Source: https://github.com/superfly/flyctl/blob/master/CONTRIBUTING.md

Manually update the GraphQL schema by navigating to the 'web' directory, generating the schema, and copying it to the flyctl gql directory.

```bash
cd web/
bundle exec rails graphql:schema:idl && cp ./schema.graphql ../flyctl/gql/schema.graphql
```

--------------------------------

### WintunGetAdapterName

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Retrieves the name of a Wintun adapter.

```APIDOC
## WintunGetAdapterName()

### Description
Returns the name of the Wintun adapter.

### Parameters
#### Path Parameters
- **Adapter** (WINTUN_ADAPTER_HANDLE) - Required - Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter.
- **Name** (WCHAR *) - Required - Pointer to a string buffer to receive the adapter name.

### Returns
- Nonzero if the function succeeds.
- Zero if the function fails. Call GetLastError for extended error information.
```

--------------------------------

### WintunGetRunningDriverVersion

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Determines the version of the Wintun driver currently loaded.

```APIDOC
## WintunGetRunningDriverVersion()

### Description
Determines the version of the Wintun driver currently loaded.

### Returns
- The version number if the function succeeds.
- Zero if the function fails. Call GetLastError for extended error information. Possible errors include ERROR_FILE_NOT_FOUND if Wintun is not loaded.
```

--------------------------------

### List Active WireGuard Peers

Source: https://context7.com/superfly/flyctl/llms.txt

Displays a list of currently active WireGuard peers configured for a specific organization, used for private network connectivity.

```bash
fly wireguard list --org my-org
```

--------------------------------

### Send Wintun Packets

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Allocates a buffer for sending a packet, copies the data, and sends it through the Wintun session. Handles potential buffer overflow errors.

```C
BYTE *OutgoingPacket = WintunAllocateSendPacket(Session, PacketDataSize);
if (OutgoingPacket)
{
    memcpy(OutgoingPacket, PacketData, PacketDataSize);
    WintunSendPacket(Session, OutgoingPacket);
}
else if (GetLastError() != ERROR_BUFFER_OVERFLOW) // Silently drop packets if the ring is full
    Log(L"Packet write failed");
```

--------------------------------

### WintunSetLogger

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Sets a callback function to be used as the global logger for Wintun events.

```APIDOC
## WintunSetLogger()

### Description
Sets the logger callback function. This function can be called from various threads concurrently. If logging requires serialization, it must be handled within the callback.

### Parameters
#### Path Parameters
- **NewLogger** (WINTUN_LOGGER_CALLBACK) - Required - Pointer to the callback function to use as the new global logger. Set to NULL to disable logging.
```

--------------------------------

### Receive Wintun Packets

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Continuously attempts to receive packets from a Wintun session. If no packet is available, it waits on a read-wait event. Errors during read operations are logged.

```C
for (;;)
{
    DWORD IncomingPacketSize;
    BYTE *IncomingPacket = WintunReceivePacket(Session, &IncomingPacketSize);
    if (IncomingPacket)
    {
        DoSomethingWithPacket(IncomingPacket, IncomingPacketSize);
        WintunReleaseReceivePacket(Session, IncomingPacket);
    }
    else if (GetLastError() == ERROR_NO_MORE_ITEMS)
        WaitForSingleObject(WintunGetReadWaitEvent(Session), INFINITE);
    else
    {
        Log(L"Packet read failed");
        break;
    }
}
```

--------------------------------

### WINTUN_MAX_IP_PACKET_SIZE Macro

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Defines the maximum size for an IP packet that Wintun can handle.

```C
#define WINTUN_MAX_IP_PACKET_SIZE   0xFFFF
```

--------------------------------

### WintunEndSession

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Ends a Wintun session.

```APIDOC
## WintunEndSession()

### Description
Ends a Wintun session.

### Parameters
#### Path Parameters
- **Session** (WINTUN_SESSION_HANDLE) - Required - Wintun session handle obtained with WintunStartSession.
```

--------------------------------

### Fetch Buffered Logs Only

Source: https://context7.com/superfly/flyctl/llms.txt

Retrieves only the logs that are currently buffered, without continuously tailing new logs. Use `--no-tail` to disable live streaming.

```bash
fly logs -a my-app --no-tail
```

--------------------------------

### WINTUN_ENUM_CALLBACK Typedef

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Defines the callback function signature for WintunEnumAdapters. It is called for each adapter in the pool and returns a boolean to indicate whether to continue iteration.

```C
typedef BOOL(* WINTUN_ENUM_CALLBACK) (WINTUN_ADAPTER_HANDLE Adapter, LPARAM Param);
```

--------------------------------

### WINTUN_ADAPTER_HANDLE

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

A type definition for a handle representing a Wintun adapter.

```APIDOC
## WINTUN_ADAPTER_HANDLE

`typedef void* WINTUN_ADAPTER_HANDLE`

A handle representing Wintun adapter.
```

--------------------------------

### WINTUN_MAX_RING_CAPACITY

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Defines the maximum ring capacity for a Wintun session.

```APIDOC
## WINTUN_MAX_RING_CAPACITY

`#define WINTUN_MAX_RING_CAPACITY   0x4000000 /* 64MiB */`

Maximum ring capacity.
```

--------------------------------

### WintunSendPacket

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Sends a packet that has been allocated and filled using WintunAllocateSendPacket.

```APIDOC
## WintunSendPacket

### Description
Sends a packet to the Wintun driver. This function should be called after allocating a buffer with `WintunAllocateSendPacket` and copying the packet data into it.

### Function Signature
`void WintunSendPacket(WINTUN_SESSION_HANDLE Session, BYTE *Packet)`

### Parameters

*   **Session** (WINTUN_SESSION_HANDLE) - The handle to the Wintun session.
*   **Packet** (BYTE *) - A pointer to the packet buffer previously allocated by `WintunAllocateSendPacket`.
```

--------------------------------

### WintunAllocateSendPacket

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Allocates a buffer for sending a packet. The buffer size should not exceed WINTUN_MAX_IP_PACKET_SIZE.

```APIDOC
## WintunAllocateSendPacket

### Description
Allocates a buffer in the Wintun session's ring buffer for sending a packet. The caller is responsible for copying the packet data into the returned buffer and then calling `WintunSendPacket`.

### Function Signature
`BYTE *WintunAllocateSendPacket(WINTUN_SESSION_HANDLE Session, DWORD PacketSize)`

### Parameters

*   **Session** (WINTUN_SESSION_HANDLE) - The handle to the Wintun session.
*   **PacketSize** (DWORD) - The size of the packet to be sent.

### Return Value
A pointer to the allocated buffer for the packet, or NULL if allocation fails (e.g., if the ring buffer is full).
```

--------------------------------

### WintunReceivePacket

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Retrieves a single packet from the Wintun session's buffer. The retrieved packet's content can be modified, and the buffer must be released using WintunReleaseReceivePacket.

```APIDOC
## WintunReceivePacket()

### Description
Retrieves one or more packets. After consuming the packet content, call WintunReleaseReceivePacket with the returned Packet to release the internal buffer. This function is thread-safe.

### Parameters
#### Path Parameters
- **Session** (WINTUN_SESSION_HANDLE) - Required - Wintun session handle obtained with WintunStartSession.
- **PacketSize** (DWORD *) - Required - Pointer to a DWORD to receive the packet size.

### Returns
- A pointer to the layer 3 IPv4 or IPv6 packet if the function succeeds. The client may modify its content.
- NULL if the function fails. Call GetLastError for extended error information. Possible errors include ERROR_HANDLE_EOF (Wintun adapter is terminating), ERROR_NO_MORE_ITEMS (Wintun buffer is exhausted), and ERROR_INVALID_DATA (Wintun buffer is corrupt).
```

--------------------------------

### WintunGetAdapterLuid

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Retrieves the LUID (Locally Unique Identifier) of a Wintun adapter.

```APIDOC
## WintunGetAdapterLuid()

### Description
Returns the LUID of the adapter.

### Parameters
#### Path Parameters
- **Adapter** (WINTUN_ADAPTER_HANDLE) - Required - Adapter handle obtained with WintunOpenAdapter or WintunCreateAdapter.
- **Luid** (NET_LUID *) - Required - Pointer to a NET_LUID structure to receive the adapter's LUID.
```

--------------------------------

### List All Health Check Results

Source: https://context7.com/superfly/flyctl/llms.txt

Retrieves and displays the status of all health checks configured for machines within an application.

```bash
fly checks list -a my-app
```

--------------------------------

### WINTUN_ADAPTER_HANDLE Typedef

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Defines a handle representing a Wintun adapter. It is a void pointer.

```C
typedef void* WINTUN_ADAPTER_HANDLE;
```

--------------------------------

### Ping WireGuard Agent

Source: https://context7.com/superfly/flyctl/llms.txt

Sends a ping request to the running WireGuard agent to verify its status and responsiveness.

```bash
fly agent ping
```

--------------------------------

### Set flyctl Environment Variables

Source: https://context7.com/superfly/flyctl/llms.txt

Set these environment variables to configure flyctl behavior, such as authentication, default app, region, and API endpoints. This is particularly useful for CI/CD pipelines.

```bash
export FLY_API_TOKEN="fo1_abc123..."
export FLY_APP="my-app"
export FLY_REGION="ord"
export FLY_ORG="my-org"
export FLY_API_BASE_URL="https://api.fly.io"
export FLY_FLAPS_BASE_URL="https://api.machines.dev"
```

--------------------------------

### WintunFreeAdapter

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Releases resources associated with a Wintun adapter handle. This function should be called to free the adapter handle obtained from WintunCreateAdapter or WintunOpenAdapter.

```APIDOC
## WintunFreeAdapter

### Description
Releases Wintun adapter resources.

### Parameters
- **Adapter** (WINTUN_ADAPTER_HANDLE) - Handle to the adapter obtained with WintunOpenAdapter or WintunCreateAdapter.

### Returns
void
```

--------------------------------

### WintunDeletePoolDriver

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Deletes all Wintun adapters in a pool. If no other adapters exist, it also removes Wintun from the driver store. Typically used by uninstallers.

```APIDOC
## WintunDeletePoolDriver()

### Description
Deletes all Wintun adapters in a pool and, if no other adapters remain, removes Wintun from the driver store. This function is usually called by uninstallers.

### Parameters
#### Path Parameters
- **Pool** (const WCHAR *) - Required - Name of the adapter pool. Zero-terminated string of up to WINTUN_MAX_POOL-1 characters.
- **RebootRequired** (BOOL *) - Optional - Pointer to a boolean flag that is set to TRUE if SetupAPI suggests a reboot.

### Returns
- Nonzero if the function succeeds.
- Zero if the function fails. Call GetLastError for extended error information.
```

--------------------------------

### WINTUN_MAX_POOL Macro

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Defines the maximum length for a Wintun pool name, including the zero terminator.

```C
#define WINTUN_MAX_POOL   256
```

--------------------------------

### WintunReleaseReceivePacket

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Releases a received packet buffer, making it available for reuse.

```APIDOC
## WintunReleaseReceivePacket

### Description
Releases a packet buffer that was received using `WintunReceivePacket`, making it available for reuse by the Wintun driver.

### Function Signature
`void WintunReleaseReceivePacket(WINTUN_SESSION_HANDLE Session, BYTE *Packet)`

### Parameters

*   **Session** (WINTUN_SESSION_HANDLE) - The handle to the Wintun session.
*   **Packet** (BYTE *) - A pointer to the packet buffer to be released, as returned by `WintunReceivePacket`.
```

--------------------------------

### WintunGetReadWaitEvent

Source: https://github.com/superfly/flyctl/blob/master/deps/wintun/README.md

Retrieves a handle to an event that is signaled when packets are available for reading.

```APIDOC
## WintunGetReadWaitEvent

### Description
Retrieves a handle to a Windows event object that will be signaled when new packets are available to be read from the Wintun session. This is useful for efficient waiting when no packets are immediately available.

### Function Signature
`HANDLE WintunGetReadWaitEvent(WINTUN_SESSION_HANDLE Session)`

### Parameters

*   **Session** (WINTUN_SESSION_HANDLE) - The handle to the Wintun session.

### Return Value
A handle to the event object. This handle should not be closed by the caller.
```

--------------------------------

### Stream Logs from Specific Machine

Source: https://context7.com/superfly/flyctl/llms.txt

Filters log streaming to a particular machine within an application, identified by its machine ID.

```bash
fly logs -a my-app --machine <machine-id>
```

--------------------------------

### Allocate Dedicated IPv4 Address

Source: https://context7.com/superfly/flyctl/llms.txt

Allocates a dedicated public IPv4 address exclusively for the specified application.

```bash
fly ips allocate-v4 -a my-app
```

--------------------------------

### Restart Postgres Cluster

Source: https://context7.com/superfly/flyctl/llms.txt

Restarts all machines within the specified Postgres cluster.

```bash
fly postgres restart -a my-pg
```