Flyctl

https://github.com/superfly/flyctl
Admin
Flyctl is a command-line interface tool for managing applications and infrastructure on the Fly.io...
Tokens:258,007
Snippets:1,757
Trust Score:9.4
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Async start with error handling

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/proxy.md

Example of using proxy.Start to start a proxy asynchronously. Bind or prompt failures are returned as errors. The proxy forwards localhost:5432 to [db.internal]:5432, and the caller must cancel the context to stop it.

```go
if err := proxy.Start(ctx, &proxy.ConnectParams{
	OrganizationSlug: "acme",
	Dialer:           dialer,
	Ports:            []string{"5432"},
	RemoteHost:       "db.internal",
}); err != nil {
	// bind or prompt failures surface here
	log.Fatalf("start proxy: %v", err)
}

// localhost:5432 now forwards to [db.internal]:5432; caller must cancel ctx_to stop it
```

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

### Monitor tokens example

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/internal-config.md

Example of starting token monitoring with a callback that prints the authorization URL, and retrieving scoped IDs.

```go
done := make(chan struct{})
go func() {
	config.MonitorTokens(ctx, cfg.Tokens, func(ctx context.Context, url string) error {
		fmt.Println("please authorize:", url)
		return nil
	})
}()
orgID, appID := config.ScopedIDs(cfg.Tokens)
```

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

### Load config example

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/internal-config.md

Example of loading configuration from a YAML file using config.Load and creating a new context. Prints API base URL, organization, and verbose output, then prints all tokens.

```go
package main

import (
	"context"

	"github.com/superfly/flyctl/internal/config"
)

func main() {
	ctx := context.Background()
	cfg, err := config.Load(ctx, "/home/me/.fly/config.yml")
	if err != nil { log.Fatal(err) }
	ctx = config.NewContext(ctx, cfg)

	fmt.Println(cfg.APIBaseURL, cfg.Organization, cfg.VerboseOutput)
fmt.Println(config.Tokens(ctx).All())
}
```

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

### Usage Example: Get a client from context and call the API

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flyutil.md

Demonstrates retrieving a client from context, creating one if absent, and making API calls.

```APIDOC
## Usage Example: Get a client from context and call the API

### Description
Demonstrates retrieving a client from context, creating one if absent, and making API calls.

### Code Example
```go
package main

import (
	"context"
	"fmt"

	"github.com/superfly/flyctl/gql"
	"github.com/superfly/flyctl/internal/flyutil"
)

func main() {
	ctx := context.Background()
	client := flyutil.ClientFromContext(ctx)   // nil when never attached
	if client == nil {
		client = flyutil.NewClientFromOptions(ctx, fly.ClientOptions{Token: "flp_…"})
		ctx = flyutil.NewContextWithClient(ctx, client)
	}

	app, err := client.GetApp(ctx, "banana")
	if err != nil { log.Fatal(err) }
	fmt.Println(app.Name)

	resp, err := gql.GetNearestRegion(ctx, client.GenqClient())
	if err != nil { log.Fatal(err) }
	fmt.Println(resp.NearestRegion.Code)
}
```
```

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

### Client Usage Examples

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flypg.md

Examples of using the flypg client to list users, create users, view and update settings, and launch a cluster.

```APIDOC
## Client Usage Examples

### List users and failover errors

```go
package main

import (
	"context"
	"fmt"

	"github.com/superfly/flyctl/agent"
	"github.com/superfly/flyctl/flypg"
)

func main() {
	ctx := context.Background()
	// in a real command the dialer comes from agent.Establish(ctx, client).Dialer(…)
	var dialer agent.Dialer

	c := flypg.NewFromInstance("2a09:b0c0::1", dialer)

	users, err := c.ListUsers(ctx)
	if err != nil {
		if flypg.ErrorStatus(err) == 404 {
			fmt.Println("no such resource")
		}
		panic(err)
	}
	for _, u := range users {
		fmt.Println(u.Name)
	}
}
```

### Create a user

```go
err := c.CreateUser(ctx, "alice", "s3cret!", false)
if err != nil {
	// e.g. the instance is unreachable or the API rejected the request
	log.Fatalf("create user: %v", err)
}
exists, err := c.UserExists(ctx, "alice")
fmt.Println(exists, err)
```

### View-and-apply settings

```go
settings, err := c.ViewSettings(ctx, []string{"max_connections"}, flypg.ReplicationManager)
if err != nil { log.Fatal(err) }
for _, s := range settings.Settings {
	fmt.Printf("%s=%s (pending %v)\n", s.Name, s.Setting, s.PendingChange)
}

err = c.UpdateSettings(ctx, map[string]string{"max_connections": "200"})
if err != nil { log.Fatal(err) }
_ = c.SyncSettings(ctx) // repmgr flex only
```

### Launch a cluster

```go
launcher := flypg.NewLauncher(client)
err := launcher.LaunchMachinesPostgres(ctx, &flypg.CreateClusterInput{
	AppName:            "acme-db",
	Organization:       org,
	Region:             "lhr",
	InitialClusterSize: 3,
	Manager:           flypg.ReplicationManager,
	Guest:              &fly.MachineGuest{CPUKind: "performance", CPUs: 2, MemoryMB: 4096},
	VolumeSize:         ptr(40),
	BackupsEnabled:     true,
	Autostart:          true,
}, false)
if err != nil { log.Fatal(err) }
```
```

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

### Example fly.toml app configuration

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

Example fly.toml file showing the app name. flyctl uses the app name from this file unless overridden with the -a flag.

```bash
$ cat fly.toml
app: banana

```

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

### Start

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/proxy.md

Builds the server, binds the local listener, then launches `ProxyServer` in a goroutine and returns once the local listener is accepting.

```APIDOC
## Start

### Description
Builds the server, binds the local listener, then launches `ProxyServer` in a goroutine and returns once the local listener is accepting. Errors from the proxy loop are currently ignored.

### Function Signature
```go
func Start(ctx context.Context, p *ConnectParams) error
```

### Parameters
- **ctx** (context.Context) - Required - The context to control cancellation.
- **p** (*ConnectParams) - Required - Parameters for the connection.

### Returns
- **error** - Returned if an error occurs during setup.
```

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

### Install flyctl pre-release via install script

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

Install the latest pre-release version of flyctl using the install script.

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

```

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

### Usage examples

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/appconfig-machines.md

Examples of converting a config to a machine config, testing config errors, and rebuilding a config from machines.

```APIDOC
## Usage examples

### Convert to machine config

```go
package main

import (
	"context"

	fly "github.com/superfly/fly-go"
	"github.com/superfly/flyctl/internal/appconfig"
)

func main() {
	ctx := context.Background()
	cfg := appconfig.NewConfig()
	cfg.AppName = "banana"
	cfg.HTTPService = &appconfig.HTTPService{InternalPort: 8080}
	cfg.Mounts = []appconfig.Mount{{Source: "data", Destination: "/data"}}

	mc, err := cfg.ToMachineConfig("web", &fly.MachineConfig{
		Env: map[string]string{"KILL": "1"},
	})
	if err != nil { log.Fatal(err) }
	fmt.Println(mc.Init, mc.Mounts, mc.Restart)
}
```

### Test config errors

```go
_, err := cfg.ToTestMachineConfig(&appconfig.ServiceMachineCheck{Command: []string{"true"}}, origMachine)
var tmcErr appconfig.TestMachineConfigErr
if errors.As(err, &tmcErr) {
	fmt.Println("can't test:", tmcErr.Error(), "—", tmcErr.Suggestion())
}
```

### Rebuild config from machines

```go
machinesSet := machine.NewMachineSet(flapsClient, io, "banana", activeMachines, true)
cfg, warnings, err := appconfig.FromAppAndMachineSet(ctx, "banana", machinesSet)
if err != nil { log.Fatal(err) }
if warnings != "" { fmt.Fprintln(os.Stderr, warnings) }
fmt.Println(cfg.Services, cfg.Compute)
```
```

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

### Establish

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/agent.md

Establishes a connection to the agent daemon, starting it if necessary.

```APIDOC
## Establish

### Description
Starts the daemon if needed and returns a connected `Client`. The API client is used to wire up org state.

### Function Signature
`func Establish(ctx context.Context, apiClient wireguard.WebClient) (*Client, error)`

### Parameters
- `ctx` (context.Context) - Required - The context for the operation.
- `apiClient` (wireguard.WebClient) - Required - The API client used to wire up org state.

### Returns
- `*Client` - A connected client to the daemon.
- `error` - An error if the daemon fails to start or connect.

### Source
`agent/client.go:38-46`
```

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

### Usage Example: Logging integration

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flyutil.md

Demonstrates creating a client with logging integration from context.

```APIDOC
## Usage Example: Logging integration

### Description
Demonstrates creating a client with logging integration from context.

### Code Example
```go
opts := fly.ClientOptions{Token: "flp_…"}
client := flyutil.NewClientFromOptions(ctx, opts) // logger picked up from ctx when present
```
```

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

### Usage Example: Manually run a proxy (advanced)

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/wg-token.md

Advanced example of manually running a WebSocket WireGuard proxy.

```APIDOC
## Usage Example: Manually run a proxy (advanced)

### Description
Advanced example of manually running a WebSocket WireGuard proxy.

### Code
```go
wswg, err := wg.NewWsWgProxy()
if err != nil { log.Fatal(err) }
defer wswg.close()
if err := wswg.Connect(ctx, lifetimeCtx, "gateway.machines.dev"); err != nil {
	log.Fatal(err)
}
port, _ := wswg.Port() // hand to wireguard as endpoint 127.0.0.1:<port>
```
```

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

### View and apply settings

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flypg.md

Shows how to view settings for a specific manager, update a setting, and sync settings. The example prints each setting with its pending change status and uses SyncSettings for repmgr flex only.

```go
settings, err := c.ViewSettings(ctx, []string{"max_connections"}, flypg.ReplicationManager)
if err != nil { log.Fatal(err) }
for _, s := range settings.Settings {
	fmt.Printf("%s=%s (pending %v)\n", s.Name, s.Setting, s.PendingChange)
}

err = c.UpdateSettings(ctx, map[string]string{"max_connections": "200"})
if err != nil { log.Fatal(err) }
_ = c.SyncSettings(ctx) // repmgr flex only
```

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

### Decorate and surface errors

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flyerr.md

Complete example showing decoration with WithSuggestion, retrieving suggestion, checking ErrAbort, creating a GenericErr, and printing CLI output.

```go
package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/superfly/flyctl/internal/flyerr"
)

func main() {
	err := errors.New("no regions available")
	err = flyerr.WithSuggestion(err, "run `fly platform regions` to list regions")

	fmt.Println(flyerr.GetErrorSuggestion(err)) // the advice
	fmt.Println(errors.Is(err, flyerr.ErrAbort)) // false

	var ge flyerr.GenericErr = flyerr.GenericErr{
		Err:      "could not allocate IP",
		Descript:  "No shared IPs are available in this region.",
		Suggest:   "Try another region.",
		DocUrl:    "https://fly.io/docs/networking/ip-addresses/",
	}
	flyerr.PrintCLIOutput(ge)
}
```

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

### Usage Example: Low-level GraphQL

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flyutil.md

Demonstrates building and running a raw GraphQL request.

```APIDOC
## Usage Example: Low-level GraphQL

### Description
Demonstrates building and running a raw GraphQL request.

### Code Example
```go
req := client.NewRequest(`query { viewer { id } }`)
q, err := client.Run(req)
if err != nil { log.Fatal(err) }
fmt.Println(q.Viewer.ID)
```
```

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

### Create a user and check existence

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flypg.md

Demonstrates creating a user with a username, password, and a flag, then checking if the user exists. The example logs a fatal error if creation fails.

```go
err := c.CreateUser(ctx, "alice", "s3cret!", false)
if err != nil {
	// e.g. the instance is unreachable or the API rejected the request
	log.Fatalf("create user: %v", err)
}
exists, err := c.UserExists(ctx, "alice")
fmt.Println(exists, err)
```

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

### Install flyctl with Homebrew

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

Install flyctl via Homebrew on macOS, Linux, or WSL.

```bash
brew install flyctl

```

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

### Building a stream and writing colored output

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/iostreams.md

Shows how to create a system stream, obtain a color scheme, write bold and red text to stdout and stderr, check interactivity, disable prompting, and start a pager for long output.

```go
package main

import (
	"fmt"

	"github.com/superfly/flyctl/iostreams"
)

func main() {
	io := iostreams.System()
	cs := io.ColorScheme()

	fmt.Fprintln(io.Out, cs.Bold("bold"))
	fmt.Fprintln(io.ErrOut, cs.Red("error"))

	if !io.IsInteractive() {
		// no prompting possible (e.g. piped stdin)
	}
	io.SetNeverPrompt(true)

	_ = io.StartPager()
	defer io.StopPager()
	// io.Out now writes into the pager
	fmt.Fprintln(io.Out, "long listing…")
}
```

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

### Establish agent and resolve host

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/agent.md

Demonstrates establishing an agent, getting a dialer, resolving a host, and handling ErrNoSuchHost. Notes that deferring Kill is optional and usually unwanted because it shuts the daemon.

```go
package main

import (
	"context"
	"fmt"

	"github.com/superfly/flyctl/agent"
	"github.com/superfly/flyctl/internal/flyutil"
)

func main() {
	ctx := context.Background()
	client := flyutil.ClientFromContext(ctx)   // fly-go API client

	ac, err := agent.Establish(ctx, client)
	if err != nil { log.Fatal(err) }
	defer ac.Kill(ctx)   // optional: shuts the daemon (usually unwanted; leave running)

	dialer, err := ac.Dialer(ctx, "acme", "")
	if err != nil { log.Fatal(err) }
	ctx = agent.DialerWithContext(ctx, dialer)

	addr, err := ac.Resolve(ctx, "acme", "db.internal", "")
	if err != nil {
		if err == agent.ErrNoSuchHost {
			log.Fatal("no such host")
		}
		log.Fatal(err)
	}
	fmt.Println(addr)
}

```

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

### Run go run to update a machine

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

Example command to update a machine using go run. Slower startup than a prebuilt binary.

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

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

### Usage example: Logger from env and context

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/logging.md

Shows creating a logger from the LOG_LEVEL environment variable and storing/retrieving it from a context.

```go
l := logger.FromEnv(os.Stderr)   // respects LOG_LEVEL
ctx := logger.NewContext(context.Background(), l)
got := logger.MaybeFromContext(ctx)  // non-nil
maybe := logger.MaybeFromContext(context.Background()) // nil
```

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

### Load config

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/internal-config.md

Example of loading the flyctl configuration from a file and creating a context.

```APIDOC
## Load config

### Description
Example of loading the flyctl configuration from a file and creating a context.

### Code Example
```go
package main

import (
	"context"

	"github.com/superfly/flyctl/internal/config"
)

func main() {
	ctx := context.Background()
	cfg, err := config.Load(ctx, "/home/me/.fly/config.yml")
	if err != nil { log.Fatal(err) }
	ctx = config.NewContext(ctx, cfg)

	fmt.Println(cfg.APIBaseURL, cfg.Organization, cfg.VerboseOutput)
	fmt.Println(config.Tokens(ctx).All())
}
```
```

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

### NewServer

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/proxy.md

Constructs the server without starting the accept loop.

```APIDOC
## NewServer

### Description
Constructs the server without starting the accept loop. It sets up the destinations, establishes the agent, and optionally prompts for an instance or resolves a remote host.

### Function Signature
```go
func NewServer(ctx context.Context, p *ConnectParams) (*Server, error)
```

### Parameters
- **ctx** (context.Context) - Required - The context for agent establishment and DNS resolution.
- **p** (*ConnectParams) - Required - Connection parameters, including organization slug, bind address, ports, and remote host.

### Returns
- **\*Server** - The constructed server.
- **error** - Returned if an error occurs during construction.

### Behavior
- If `PromptInstance` is set, prompts for an instance and sets the remote address.
- If `RemoteHost` is provided, waits for DNS resolution and sets the remote address.
- Binds to the local address using TCP or Unix sockets depending on the port specification.
- Prints a proxy startup message.
```

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

### Start a Wintun Session

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

Initializes a tunnel session on a previously created adapter.

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

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

### Blocking proxy with both ports specified

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/proxy.md

Example of using proxy.Connect to set up a blocking proxy. It requires an established agent tunnel dialer from context. The example maps local port 8080 to remote port 80 on the specified remote host.

```go
package main

import (
	"context"
	"os"
	"os/signal"

	"github.com/superfly/flyctl/agent"
	"github.com/superfly/flyctl/proxy"
)

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()

	// dialer comes from an established agent tunnel (see agent package)
	dialer := agent.DialerFromContext(ctx)

	err := proxy.Connect(ctx, &proxy.ConnectParams{
		AppName:          "banana",
		OrganizationSlug: "acme",
		Dialer:           dialer,
		BindAddr:         "127.0.0.1",
		Ports:            []string{"8080", "80"},   // local:8080 → remote:80
		RemoteHost:       "9185f7a1",
		Network:           "",
	})
	if err != nil {
		os.Exit(1)
	}
}
```

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

### List users and handle failover errors

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flypg.md

Shows how to create a flypg client from an instance address and dialer, list users, and handle errors using flypg.ErrorStatus. The example prints 'no such resource' when a 404 error occurs.

```go
package main

import (
	"context"
	"fmt"

	"github.com/superfly/flyctl/agent"
	"github.com/superfly/flyctl/flypg"
)

func main() {
	ctx := context.Background()
	// in a real command the dialer comes from agent.Establish(ctx, client).Dialer(…)
	var dialer agent.Dialer

	c := flypg.NewFromInstance("2a09:b0c0::1", dialer)

	users, err := c.ListUsers(ctx)
	if err != nil {
		if flypg.ErrorStatus(err) == 404 {
			fmt.Println("no such resource")
		}
		panic(err)
	}
	for _, u := range users {
		fmt.Println(u.Name)
	}
}
```

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

### Usage example: Wire into the API client

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/logging.md

Shows how to pass the logger from context to the fly-go API client via ClientOptions.

```go
opts := fly.ClientOptions{Token: token}
if l := logger.MaybeFromContext(ctx); l != nil {
	opts.Logger = l  // fly-go logs via the same logger
}
client := flyutil.NewClientFromOptions(ctx, opts)
```

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

### Unix socket with interactive instance selection

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/proxy.md

Example of using proxy.Connect with a Unix socket path and PromptInstance set to true for interactive instance selection. The proxy listens on /tmp/fly-proxy.sock.

```go
err := proxy.Connect(ctx, &proxy.ConnectParams{
	AppName:          "banana",
	OrganizationSlug: "acme-org",
	Dialer:           dialer,
	Ports:            []string{"/tmp/fly-proxy.sock"}, // unix socket path
	PromptInstance:   true,
})
if err != nil { log.Fatal(err) }
```

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

### Get client from context and call the API

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flyutil.md

Shows how to obtain a client from context, create one if absent, and use it to call GetApp and gql.GetNearestRegion. Requires a valid token and a context with the client attached.

```go
package main

import (
	"context"
	"fmt"

	"github.com/superfly/flyctl/gql"
	"github.com/superfly/flyctl/internal/flyutil"
)

func main() {
	ctx := context.Background()
	client := flyutil.ClientFromContext(ctx)   // nil when never attached
	if client == nil {
		client = flyutil.NewClientFromOptions(ctx, fly.ClientOptions{Token: "flp_…"})
		ctx = flyutil.NewContextWithClient(ctx, client)
	}

	app, err := client.GetApp(ctx, "banana")
	if err != nil { log.Fatal(err) }
	fmt.Println(app.Name)

	resp, err := gql.GetNearestRegion(ctx, client.GenqClient()
	if err != nil { log.Fatal(err) }
	fmt.Println(resp.NearestRegion.Code)
}
```

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

### StartDaemon

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/agent.md

Starts the background agent daemon if not already running, returning a connected client.

```APIDOC
## StartDaemon

### Description
Starts the background agent daemon (`flyctl agent run`) if not already running. It takes a start lock, writes a log file, spawns the current executable with `"agent"` `"run"` and the log file path, exports `FLY_API_TOKEN` (when tokens don't come from a config file), and waits for the daemon to come up on the socket. If another daemon wins the lock, it connects to it.

### Function Signature
`func StartDaemon(ctx context.Context) (*Client, error)`

### Parameters
- `ctx` (context.Context) - Required - The context for the operation.

### Returns
- `*Client` - A connected client to the daemon.
- `error` - An error if the daemon fails to start or connect. Possible errors include lock contention (`alreadyStartingError`) and unexpected exit (`startError`).

### Source
`agent/start.go:28-130`
```

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

### Usage Example: WireGuard peer management

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flyutil.md

Demonstrates creating, listing, and validating WireGuard peers.

```APIDOC
## Usage Example: WireGuard peer management

### Description
Demonstrates creating, listing, and validating WireGuard peers.

### Code Example
```go
peer, err := client.CreateWireGuardPeer(ctx, "org_123", "lhr", "laptop", pubkeyB64, "")
if err != nil { log.Fatal(err) }
fmt.Println(peer.Peerip)

peers, err := client.GetWireGuardPeers(ctx, "acme")
invalid, err := client.ValidateWireGuardPeers(ctx, []string{peer.Peerip})
fmt.Println(len(invalid), len(peers))
```
```

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

### Usage example: Terminal facade

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/logging.md

Shows how to use the terminal package's package-level functions for logging. Includes a switch on GetLogLevel() to conditionally enable verbose mode.

```go
package main

import "github.com/superfly/flyctl/terminal"

func main() {
	terminal.Debug("debugging detail")
	terminal.Infof("deploying %s", "banana")
	terminal.Warn("disk almost full")
	terminal.Error("something broke")

	switch terminal.GetLogLevel() {
	case logger.Debug:
		// wireguard-go verbose mode etc.
	}
}
```

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

### Rebuild config from machines

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/appconfig-machines.md

Example of rebuilding a Config from a machine set using FromAppAndMachineSet. Creates a MachineSet with a flaps client and active machines, then calls the function. Prints warnings to stderr and the resulting Services and Compute fields.

```go
machinesSet := machine.NewMachineSet(flapsClient, io, "banana", activeMachines, true)
cfg, warnings, err := appconfig.FromAppAndMachineSet(ctx, "banana", machinesSet)
if err != nil { log.Fatal(err) }
if warnings != "" { fmt.Fprintln(os.Stderr, warnings) }
fmt.Println(cfg.Services, cfg.Compute)
```

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

### Namespaced config access

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flyctl.md

Shows how to use ConfigNS to set and get keys with a namespace prefix, and how root-namespace access is unprefixed.

```go
import (
	"github.com/superfly/flyctl/flyctl"
	"github.com/spf13/viper"
)

func main() {
	flyctl.InitConfig()
	cfg := flyctl.ConfigNS("postgres")
	cfg.Set("region", "lhr")
	// reads viper key "postgres.region"
	region := cfg.GetString("region")
	_ = region

	// root-namespace access is unprefixed
	root := flyctl.ConfigNS(flyctl.NSRoot)
	root.Set(flyctl.ConfigAppName, "banana")
	_ = viper.GetString("app") // "banana"
}
```

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

### Convert config to machine config

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/appconfig-machines.md

Example of converting an appconfig.Config to a fly.MachineConfig using ToMachineConfig. Sets AppName, HTTPService, and Mounts, then passes a base MachineConfig with an Env map. Prints the resulting Init, Mounts, and Restart fields.

```go
package main

import (
	"context"

	fly "github.com/superfly/fly-go"
	"github.com/superfly/flyctl/internal/appconfig"
)

func main() {
	ctx := context.Background()
	cfg := appconfig.NewConfig()
	cfg.AppName = "banana"
	cfg.HTTPService = &appconfig.HTTPService{InternalPort: 8080}
	cfg.Mounts = []appconfig.Mount{{Source: "data", Destination: "/data"}}

	mc, err := cfg.ToMachineConfig("web", &fly.MachineConfig{
		Env: map[string]string{"KILL": "1"},
	})
	if err != nil { log.Fatal(err) }
	fmt.Println(mc.Init, mc.Mounts, mc.Restart)
}
```

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

### WireGuard peer management

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flyutil.md

Examples of creating, listing, and validating WireGuard peers. Note the code has syntax errors (missing closing parentheses) as shown in the source.

```go
peer, err := client.CreateWireGuardPeer(ctx, "org_123", "lhr", "laptop", pubkeyB64, "")
if err != nil { log.Fatal(err) }
fmt.Println(peer.Peerip)

peers, err := client.GetWireGuardPeers(ctx, "acme")
invalid, err := client.ValidateWireGuardPeers(ctx, []string{peer.Peerip})
fmt.Println(len(invalid), len(peers)
```

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

### Terminal probing and process attrs

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/cmdutil.md

Example usage of IsTerminal and SetSysProcAttributes, showing terminal detection and subprocess setup.

```go
if cmdutil.IsTerminal(os.Stdout) {
	fmt.Println("tty")
}
cmd := exec.Command("flyctl", "agent", "run")
cmdutil.SetSysProcAttributes(cmd)
// Unix: child reaps when parent dies
```

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

### Usage example: Standalone logger with file sink

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/logging.md

Shows creating a standalone logger with explicit level and TTY-ness, and enabling file logging via AndLogToFile().

```go
import (
	"os"

	"github.com/superfly/flyctl/internal/logger"
)

func main() {
	l := logger.New(os.Stdout, logger.Debug, true).AndLogToFile()
	l.Infof("starting worker %d", 1)
	l.Debug("low-level detail")
	l.Error("boom")
	_ = l.Level() // logger.Debug
}
```

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

### Direct usage of IsV6

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/ip.md

Direct usage example showing expected outputs for various inputs: IPv6 literal, bracketed IPv6, IPv4, DNS name, and invalid string.

```go
package main

import (
	"fmt"

	"github.com/superfly/flyctl/ip"
)

func main() {
	fmt.Println(ip.IsV6("2a09:b0c0::1")) // true
	fmt.Println(ip.IsV6("[2a09:b0c0::1]")) // true (brackets stripped)
	fmt.Println(ip.IsV6("10.0.0.1"))    // false
	fmt.Println(ip.IsV6("db.internal"))       // false (DNS name)
	fmt.Println(ip.IsV6("not-an-ip"))      // false
}
```

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

### Observe failure modes with tun.Done() and tun.Err()

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/wg-token.md

Example of observing failure modes of a tunnel. It starts a goroutine that waits on tun.Done(), then inspects tun.Err() to distinguish a normal close (nil), a malformed reply (wg.ErrMalformedReply), or any other termination error, logging accordingly.

```go
go func() {
	select {
	case <-tun.Done():
		err := tun.Err()
		switch {
		case err == nil: // owner closed
		case errors.Is(err, wg.ErrMalformedReply):
			log.Printf("gateway protocol problem: %v", err)
		default:
			log.Printf("tunnel terminated: %v", err)
		}
	}
}()
```

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

### Launch a Postgres cluster

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flypg.md

Shows how to launch a Postgres cluster using the Launcher with a CreateClusterInput configuration. The example sets app name, organization, region, cluster size, manager, guest machine specs, volume size, and backup/autostart flags.

```go
launcher := flypg.NewLauncher(client)
err := launcher.LaunchMachinesPostgres(ctx, &flypg.CreateClusterInput{
	AppName:            "acme-db",
	Organization:       org,
	Region:             "lhr",
	InitialClusterSize: 3,
	Manager:           flypg.ReplicationManager,
	Guest:              &fly.MachineGuest{CPUKind: "performance", CPUs: 2, MemoryMB: 4096},
	VolumeSize:         ptr(40),
	BackupsEnabled:     true,
	Autostart:          true,
}, false)
if err != nil { log.Fatal(err) }
```

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

### Install specific flyctl version via install script

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

Install a specific version of flyctl (e.g., 0.0.200) using the install script.

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

```

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

### Install latest flyctl via install script

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

Install the latest version of flyctl using the official install script on macOS, Linux, or WSL.

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

```

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

### Install flyctl on Windows via PowerShell

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

Install flyctl on Windows using the PowerShell install script.

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

```

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

### Get changed-flag names

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flag.md

Shows how to get the names of flags that have been changed from their default values.

```APIDOC
## Get changed-flag names

### Description
Use flag.GetFlagsName to retrieve the names of flags that have been changed from their defaults, optionally excluding certain flags.

### Usage
```go
names := flag.GetFlagsName(ctx, []string{"yes"})
for _, n := range names { fmt.Println("changed:", n) }
```

### Functions
- **flag.GetFlagsName(ctx, exclude []string)** - Returns a slice of flag names that have been changed, excluding the names in the exclude slice.
```

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

### Usage Example: Observe failure modes

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/wg-token.md

Example of handling tunnel failure modes.

```APIDOC
## Usage Example: Observe failure modes

### Description
Example of observing tunnel failure modes using the Done and Err methods.

### Code
```go
go func() {
	select {
	case <-tun.Done():
		err := tun.Err()
		switch {
		case err == nil: // owner closed
		case errors.Is(err, wg.ErrMalformedReply):
			log.Printf("gateway protocol problem: %v", err)
		default:
			log.Printf("tunnel terminated: %v", err)
		}
	}
}()
```
```

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

### Create an app with defaults and error handling

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/gql.md

Creates an app using gql.CreateApp with default input. On error, it logs a fatal message. On success, it prints the app name and deployed status.

```go
resp, err := gql.CreateApp(ctx, apiClient.GenqClient(), gql.DefaultCreateAppInput())
if err != nil {
	log.Fatalf("create app: %v", err)
}
app := resp.CreateApp.GetApp()
fmt.Println("created", app.GetName(), "deployed:", app.GetDeployed())
```

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

### Usage Example: Connect with a macaroon provider

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/wg-token.md

Example of using ConnectToken with a macaroon token provider.

```APIDOC
## Usage Example: Connect with a macaroon provider

### Description
Example of connecting to a WireGuard gateway using a macaroon token provider.

### Code
```go
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/superfly/flyctl/wg"
)

func macaroonToken() string {
	// UI callback: periodically refreshed macaroon for the session
	return "eyJ…"
}

func main() {
	ctx := context.Background()
	state := &wg.WireGuardState{
		Org:         "acme",
		LocalPublic: base64Pubkey, // base64
	}

	tun, err := wg.ConnectToken(ctx, state, wg.DefaultTokenGateway, &wg.TokenAuth{
		Token:   macaroonToken,
		OrgSlug: "acme",
	})
	if err != nil {
		if ge, ok := err.(*wg.GatewayError); ok && ge.Permanent() {
			// reconnecting with the same credentials won't fix it
			panic(err)
		}
		panic(err)
	}

	defer tun.Close()
	fmt.Println("allocated peer:", state.Peer.Peerip, "expires:", tun.Provision().ExpiresAt.Format(time.RFC3339))
}
```
```

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

### Define a command with command.New

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/command.md

Shows how to create a new command using command.New with a name, short description, long help text, and a handler function. The handler uses flag.FirstArg to get the first argument and iostreams to write output. Preparation of config, client, and iostreams happens automatically before the handler runs.

```go
package mycmd

import (
	"context"

	"github.com/superfly/flyctl/internal/command"
	"github.com/superfly/flyctl/internal/flag"
)

var _ = flag.String{}

func New() *cobra.Command {
	return command.New(
		"hello [name]",
		"Say hello",
		"Long help text",
		func(ctx context.Context) error {
			name := flag.FirstArg(ctx)
			io := iostreams.FromContext(ctx)
			_, err := fmt.Fprintf(io.Out, "hello %s\n", name)
			return err
		},
		// optionally append custom preparers…
	)
}
```

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

### Construct and inspect a config

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/appconfig.md

Creates a new app config, sets app name, HTTPS service, environment variables, and processes, then converts to a definition and back. Requires importing the appconfig package.

```go
package main

import (
	"fmt"

	"github.com/superfly/flyctl/internal/appconfig"
)

func main() {
	cfg := appconfig.NewConfig()
	cfg.AppName = "banana"
	cfg.HTTPService = &appconfig.HTTPService{InternalPort: 8080, ForceHTTPS: true}
	cfg.Env = map[string]string{"FOO": "bar"}
	cfg.Processes = map[string]string{"web": "cmd/web"}

	def, err := cfg.ToDefinition()
	if err != nil { log.Fatal(err) }
	fmt.Println(def.Get("app"))

	back, err := appconfig.FromDefinition(def)
	if err != nil { log.Fatal(err) }
	fmt.Println(back.AppName)
}
```

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

### Connect and run a shell command with ssh.Client

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/ssh.md

Complete example of connecting to a machine via SSH and running a shell command. Uses ssh.Client with an address, user, dialer, private key, and certificate. The Connect method fails if the certificate pubkey is not a certificate or the key cannot be parsed. The Shell method runs 'uptime' with a SessionIO that wires stdin/stdout/stderr and optionally allocates a PTY.

```go
package main

import (
	"context"
	"fmt"

	"github.com/superfly/flyctl/ssh"
)

func main() {
	ctx := context.Background()
	client := &ssh.Client{
		Addr:       "[2a09:b0c0::1]:22",
		User:       "root",
		Dial:       dialer.DialContext,   // agent.Dialer
		PrivateKey: privateKeyPEM,        // ed25519 PEM
		Certificate: certPEM,           // issued via fly API
	}

	if err := client.Connect(ctx); err != nil {
		// certificate pubkey must be a certificate; key must parse
		log.Fatal(err)
	}
	defer client.Close()

	io := &ssh.SessionIO{
		Stdin:   os.Stdin,
		Stdout:  ioutils.NewWriteCloserWrapper(os.Stdout, func() error { return nil }),
		Stderr:  ioutils.NewWriteCloserWrapper(os.Stderr, func() error { return nil }),
		AllocPTY: false,
	}
	if err := client.Shell(ctx, io, "uptime", ssh.SessionTarget{Machine: true}); err != nil {
		log.Fatal(err)
	}
	fmt.Println("done")
}
```

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

### StartProgressIndicator()

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/iostreams.md

Starts a spinner on stderr with no message.

```APIDOC
## StartProgressIndicator()

### Description
Starts a spinner on stderr with no message. Uses character set 39 and 250 ms interval.

### Method
StartProgressIndicator
```

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

### Import the proxy package

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/proxy.md

Import the `proxy` package to use its functionality.

```go
import "github.com/superfly/flyctl/proxy"
```

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

### Monitor tokens

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/internal-config.md

Example of monitoring tokens and extracting scoped IDs.

```APIDOC
## Monitor tokens

### Description
Example of monitoring tokens and extracting scoped IDs.

### Code Example
```go
done := make(chan struct{})
go func() {
	config.MonitorTokens(ctx, cfg.Tokens, func(ctx context.Context, url string) error {
		fmt.Println("please authorize:", url)
		return nil
	})
}()
orgID, appID := config.ScopedIDs(cfg.Tokens)
```
```

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

### WintunStartSession

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

Starts a Wintun session for packet processing on the specified adapter.

```APIDOC
## WintunStartSession()

### Description
Starts a Wintun session for packet processing on the specified adapter.

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

### 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 (incl.) Must be a power of two.

### Returns
Wintun session handle. Must be released with WintunEndSession. If the function fails, the return value is NULL. To get extended error information, call GetLastError.
```

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

### Fetch an app with gql.GetApp

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/gql.md

Shows how to create a client and fetch an app by name. The response includes the app's name and hostname. Requires a valid Fly.io API token.

```go
package main

import (
	"context"
	"fmt"

	fly "github.com/superfly/fly-go"
	"github.com/superfly/flyctl/gql"
	"github.com/superfly/flyctl/internal/flyutil"
)

func main() {
	ctx := context.Background()
	client := flyutil.NewClientFromOptions(ctx, fly.ClientOptions{})
	resp, err := gql.GetApp(ctx, client.GenqClient(), "my-app")
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.App.GetName(), resp.App.GetHostname())
}
```

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

### Connect

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/wg-token.md

Establishes the websocket connection to the gateway and starts the relay and keepalive loops.

```APIDOC
## Connect

### Description
Dials the endpoint websocket, performs token exchange, and starts the relay, keepalive, and reconnect loops.

### Method
Connect

### Signature
`func (wswg *WsWgProxy) Connect(dialCtx, lifetimeCtx context.Context, endpoint string) error`

### Parameters
- `dialCtx` (context.Context) - Required - Context for the dialing operation.
- `lifetimeCtx` (context.Context) - Required - Context for the lifetime of the connection.
- `endpoint` (string) - Required - The websocket endpoint to connect to.

### Returns
- `error` - An error if the connection fails.

### Example
```go
err := proxy.Connect(ctx, lifetimeCtx, "wss://example.com")
if err != nil {
    // handle error
}
```
```

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

### Logging integration with NewClientFromOptions

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flyutil.md

Creates a client with options, picking up the logger from context when present.

```go
opts := fly.ClientOptions{Token: "flp_…"}
client := flyutil.NewClientFromOptions(ctx, opts) // logger picked up from ctx when present
```

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

### Simple table with MakeSimpleTable

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/helpers.md

Creates a simple table with headers and appends a row, then renders it to stdout.

```go
t := helpers.MakeSimpleTable(os.Stdout, []string{"NAME", "REGION"})
t.Append([]string{"banana", "lhr"})
t.Render()
```

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

### StartProgressIndicatorMsg(msg string)

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/iostreams.md

Starts a spinner with a prefix message; no-op when progress is disabled.

```APIDOC
## StartProgressIndicatorMsg(msg string)

### Description
Starts a spinner with a prefix message; no-op when progress is disabled.

### Method
StartProgressIndicatorMsg

### Parameters
- **msg** (string) - Required - The prefix message to display.
```

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

### NewLauncher

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/flypg.md

Constructs a new Launcher instance with the provided flyutil.Client.

```APIDOC
## NewLauncher

### Description
Creates a new Launcher with the given client.

### Signature
```go
func NewLauncher(client flyutil.Client) *Launcher
```

### Parameters
- **client** (flyutil.Client) - Required - The Fly.io utility client.

### Returns
- **\*Launcher** - A new Launcher instance.

```

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

### Shell method signature

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/ssh.md

Opens a session, sets the target, and attaches the provided SessionIO to execute the command.

```go
func (c *Client) Shell(ctx context.Context, sessIO *SessionIO, cmd string, target SessionTarget) error
```

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

### GetApp

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/gql.md

Gets an app by its name or slug. Returns a response containing the app information or an error.

```APIDOC
## GetApp

### Description
Gets an app's information by name. The response contains the app data and can be accessed via the `App` field.

### Method
GraphQL Query

### Endpoint
`GetApp`

### Parameters
- `ctx_` (context.Context) - Required - Cancellation/deadline context.
- `client_` (graphql.Client) - Required - The generated GraphQL client (e.g., `fly.Client`).
- `name` (string) - Required - The app name or slug.

### Returns
`*GetAppResponse` - Contains the app data (`resp.App`) and its Get* accessors. Or an error.

### Source
`gql/generated.go:4092`
```

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

### Create Wintun Adapters

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

Demonstrates creating multiple Wintun adapters within a specific pool using WintunCreateAdapter.

```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);
```

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

### Restrict to one machine

Source: https://github.com/superfly/flyctl/blob/master/_autodocs/api-reference/logs.md

Example of streaming logs for a specific machine by setting the VMID option.

```APIDOC
## Restrict to one machine

### Description
Example of streaming logs for a specific machine by setting the VMID option.

### Code Example
go
opts := &logs.LogOptions{
	AppName: "banana",
	VMID:    "9185f7a",
}
stream, _ := logs.NewNatsStream(ctx, apiClient, flapsClient, opts)
for entry := range stream.Stream(ctx, opts) {
	// NATS subject: logs.banana.*.9185f7a
	_ = entry.Meta.HTTP.Response.StatusCode
}

```
Tokens:
Raw