---
schema_version: 1
route: /t/flyctl.md
tool: "flyctl"
---

# sincecutoff.com /t/flyctl — flyctl

- name: flyctl
- kind: cli
- children: none
- homepage: <https://github.com/superfly/flyctl>

Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows.
Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json).
To stay current, read the changes feed: [`/v1/changes.md?tool=flyctl`](https://sincecutoff.com/v1/changes.md?tool=flyctl) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt).

### fly auth login supports terminal-free code flow (2026-10-08)
- slug: fly-auth-login-supports-terminal-free-code-flow-92dd4f8bd26b
- score: 0.92

How to use it:

When the browser approval is on another machine or the waiting login command was stopped, finish the pending login with the one-time code shown on the approval page. Run `fly auth login --code <one-time-code>`.

Examples:

```
fly auth login --code <one-time-code>
```

- why_it_matters: Authenticate with flyctl in an environment without a terminal.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.115>, <https://github.com/superfly/flyctl/blob/v0.4.115/internal/command/auth/login.go>
- gotchas: "Version: v0.4.115"; "--code <one-time-code> (required): One-time code shown on the approval page; mutually exclusive with `--interactive`, `--email`, `--password`, and `--otp`."; "Prerequisite: A browser login must be waiting for approval, and its approval page must show the one-time code."

### flyctl supports FLY_NO_PROMPT (2026-10-08)
- slug: flyctl-supports-fly-no-prompt-520144f5c0bf
- score: 0.93

How to use it:

When running a flyctl command in automation that must not prompt, set `FLY_NO_PROMPT` before invoking it. The exact value and its documented behavior beyond “never prompt” were not found in official documentation.

- why_it_matters: Run a flyctl command in automation that must not prompt for input.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.115>
- gotchas: "Version: v0.4.115"

### fly mpg users rotate-password rotates a managed Postgres user password (2026-10-06)
- slug: fly-mpg-users-rotate-password-rotates-a-managed-postgres-user-password-bde83abb5ff3
- score: 0.94

How to use it:

For an MPG v2 cluster, run `fly mpg users rotate-password <CLUSTER_ID> --username <USER>` and confirm the rotation with `--yes` for noninteractive or JSON use. If the server reports `sessions_not_terminated`, print the current credentials and exit with failure; do not retry rotation.

Examples:

```
fly mpg users rotate-password <CLUSTER_ID> --username <USER>
```

```
fly mpg users rotate-password <CLUSTER_ID> --username <USER> --yes --json
```

```
fly mpg users rotate-password <CLUSTER_ID> --username <USER> --kill-sessions --yes
```

- why_it_matters: When rotating a managed Postgres user password, run the command and recover the current credentials if rotation succeeds but session termination fails.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.113>, <https://github.com/superfly/flyctl/pull/5285>, <https://github.com/superfly/flyctl/blob/v0.4.113/internal/command/mpg/users.go>
- gotchas: "Version: v0.4.113"; "CLUSTER_ID (required): Target cluster ID; required when using `--json`."; "--username (required): User whose password to rotate; required with `--json` or in noninteractive use."; "--yes: Skip confirmation; required for `--json` and noninteractive use."; "--json: Output credentials as JSON; requires `--yes`, `CLUSTER_ID`, and `--username`."; "--kill-sessions: Terminate the user's existing database sessions after rotation."; "Prerequisite: The command requires an authenticated Fly session and a macaroon token."; "Prerequisite: Supported only for MPG v2 clusters; v1 clusters must be migrated to v2 first."; "Rotation requires explicit confirmation."

### fly ssh console adds --no-container (2026-08-13)
- slug: fly-ssh-console-adds-no-container-0440551a4fda
- score: 0.92

How to use it:

When opening an SSH console to a Fly app, use `fly ssh console --no-container` to connect to the machine itself rather than one of its containers.

Examples:

```
fly ssh console --no-container
```

- why_it_matters: Open an SSH console without a container when working on a Fly app.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.83>, <https://docs.fly.io/flyctl/cmd/fly_ssh_console>, <https://github.com/superfly/flyctl/blob/v0.4.83/internal/command/ssh/console.go>
- gotchas: "Version: v0.4.83"; "--no-container: Connect to the machine itself rather than to one of its containers. Mutually exclusive with `--container`."; "--container: Selects a container to connect to; cannot be used with `--no-container`."; "Prerequisite: The command requires a Fly session and an app name; it connects to a running app instance."

### flyctl [build] accepts Dockerfile URLs (2026-07-27)
- slug: flyctl-build-accepts-dockerfile-urls-b8fe9c6e325f
- score: 0.97

How to use it:

When `[build].dockerfile` is hosted remotely, set it to the Dockerfile URL and deploy from the repository root; flyctl keeps the project root as the default build context. The URL is downloaded when a Dockerfile builder needs it and the same copy is reused throughout the deploy.

Examples:

```
[build]
dockerfile = "<Dockerfile URL>"

flyctl deploy
```

- why_it_matters: Deploy a repository whose `[build] dockerfile` is hosted remotely while retaining the local build context.
- before: Set `[build] dockerfile` to a local path for Dockerfile builds.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.75>, <https://github.com/superfly/flyctl/pull/5021>, <https://github.com/superfly/docs/blob/main/reference/configuration.html.markerb>, <https://github.com/superfly/flyctl>
- gotchas: "Version: v0.4.75"; "[build].dockerfile: Accepts a relative Dockerfile path or a URL; defaults to `Dockerfile` in the application root. It does not change the Docker context, which defaults to the project root."; "Prerequisite: Install flyctl and sign in to a Fly account before deploying."; "The URL is fetched only when a Dockerfile builder needs it."; "Downloads have a 30 second timeout and a 10 MiB limit."; "The downloaded file is stored in a private temporary directory that is cleaned up before deploy continues."; "Redirects drop query-bearing Referer headers and refuse HTTPS-to-HTTP downgrades."; "Local Dockerfiles and non-Dockerfile builds are unchanged."

### fly logs adds machine selection (2026-07-22)
- slug: fly-logs-adds-machine-selection-3cf3ff2be05a
- score: 0.95

How to use it:

When debugging an app with multiple Machines, run `fly logs -m <machine-id>` to filter logs to one Machine, or `fly logs -s` to select one interactively. The command requires an authenticated Fly session and an app name.

Examples:

```
fly logs -m <machine-id>
```

```
fly logs -s
```

- why_it_matters: Narrow log inspection to one Machine while debugging an app with multiple Machines.
- before: List Machines and copy a Machine ID before narrowing logs to one Machine.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.74>, <https://github.com/superfly/flyctl/pull/5018>, <https://github.com/superfly/flyctl/blob/v0.4.74/internal/command/logs/logs.go>
- gotchas: "Version: v0.4.74"; "-m, --machine <machine-id>: Filter logs by Machine ID. Alias: `--instance` / `-i`."; "-s, --select: Select a Machine from a list; cannot be used with `--machine`."; "Prerequisite: Requires an authenticated Fly session and an app name; the app can be determined from `fly.toml` or supplied with the app flag."; "The `-s` selection is interactive."; "The `--instance/-i` alias is hidden but still works."

### fly mpg database extensions list, enable, and disable commands (2026-07-08)
- slug: fly-mpg-database-extensions-list-enable-and-disable-commands-898ca75be6a3
- score: 0.98

How to use it:

When managing extensions on an MPG cluster from a non-interactive workflow, use the documented list, enable, or disable command for the target database. The current official CLI docs use `databases` in the command path; the card and release note use `database`, so verify the installed CLI’s syntax before running it.

Examples:

```
fly mpg databases extensions list <CLUSTER_ID> [flags]
```

```
fly mpg databases extensions enable <EXTENSION> --cluster <CLUSTER_ID> --database <DATABASE> [--schema <SCHEMA>] [--create-schema]
```

```
fly mpg databases extensions disable <EXTENSION> --cluster <CLUSTER_ID> --database <DATABASE> [--force]
```

- why_it_matters: Manage extensions on a Managed Postgres cluster from a non-interactive workflow such as CI.
- before: The release note says extensions could previously only be enabled via the dashboard.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.68>, <https://github.com/superfly/flyctl/pull/4983>, <https://fly.io/docs/flyctl/mpg-databases-extensions-list/>, <https://fly.io/docs/flyctl/mpg-databases-extensions-enable/>, <https://docs.fly.io/flyctl/cmd/fly_mpg_databases_extensions_disable>
- gotchas: "Version: v0.4.68"; "<CLUSTER_ID> (required): Target cluster ID for `list`."; "--database, -d: Target database within the cluster; listed as an option for `list`."; "--json, -j: Output list results as JSON."; "<EXTENSION> (required): Postgres extension to enable or disable."; "--cluster, -c (required): Target cluster ID for enable or disable."; "--database, -d (required): Target database within the cluster for enable or disable."; "--schema: Schema in which to create the extension; default is `public`."; "--create-schema: Create the schema if it does not exist."; "--force: Drop dependent objects as well (`CASCADE`) when disabling."; "--access-token, -t: Fly API access token global option."; "Prerequisite: Use a flyctl version that includes the commands; release v0.4.68 added them."; "Prerequisite: For enable or disable, authenticate with a Fly API access token; docs list `--access-token` as a global option."; "Applies to new V2 clusters and existing V1 clusters."; "Docs conflict: Card and release note use `fly mpg database extensions ...`; current official CLI docs document `fly mpg databases extensions ...` (plural). The official v0.4.68 source is at https://github.com/superfly/flyctl/blob/v0.4.68/internal/command/mpg/extensions.go, but the retrieved source page did not expose command usage text."

### flyctl tokens create readonly adds an organization flag (2026-04-30)
- slug: flyctl-tokens-create-readonly-adds-an-organization-flag-3a477b9f6afa
- score: 0.91

How to use it:

When creating a read-only token for an organization, run `flyctl tokens create readonly -o <org>`.

Examples:

```
flyctl tokens create readonly -o <org>
```

- why_it_matters: Create a read-only token scoped to an organization.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.44>
- gotchas: "Version: v0.4.44"; "-o, --org <org> (required): Specifies the organization for `tokens create readonly`."

### flyctl machine run and update add --cachedrive-size (2026-04-08)
- slug: flyctl-machine-run-and-update-add-cachedrive-size-dc82027c76bb
- score: 0.90

How to use it:

When setting a cache drive size while running or updating a machine, pass `--cachedrive-size <size>` to `fly machine run` or `fly machine update`. Use a plain number in MB or a human-readable size; `0` disables the cache drive.

Examples:

```
fly machine run <image> --cachedrive-size <size>
```

```
fly machine update <machine_id> --cachedrive-size <size>
```

- why_it_matters: Set a cached drive size when running or updating a machine.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.32>, <https://github.com/superfly/flyctl/blob/v0.4.32/internal/command/machine/run.go>, <https://github.com/superfly/flyctl/blob/v0.4.32/internal/command/machine/update.go>
- gotchas: "Version: v0.4.32"; "--cachedrive-size <size>: Cache drive size in MB; accepts a plain number in MB or a human-readable size such as `512mb` or `10gb`. Set to `0` to disable."; "<image> (required): Image argument for `run`."; "<machine_id>: Machine ID argument for `update`; the command definition allows it to be omitted."; "Prerequisite: The command requires a flyctl session."

### flyctl machine run and update accept --vm-max-memory (2026-03-23)
- slug: flyctl-machine-run-and-update-accept-vm-max-memory-1bcd5e429b48
- score: 0.92

How to use it:

When running a new machine or updating an existing one, pass `--vm-max-memory <memory>` to set its maximum memory in MB. The v0.4.27 source documents the flag as hidden and rejects zero or invalid sizes.

Examples:

```
fly machine run <image> --vm-max-memory <memory> --app <app-name>
```

```
fly machine update <machine-id> --vm-max-memory <memory> --app <app-name>
```

- why_it_matters: Set a machine's maximum memory while running or updating it.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.27>, <https://github.com/superfly/flyctl/pull/4793>, <https://github.com/superfly/flyctl/blob/v0.4.27/internal/flag/machines.go>, <https://github.com/superfly/flyctl/blob/master/internal/command/machine/run.go>
- gotchas: "Version: v0.4.27"; "--vm-max-memory <memory>: Maximum memory, in megabytes, allowed for the VM. Parsed as a size; zero is rejected. The flag is hidden and has no alias."; "<image> (required): Image or Dockerfile path argument for `machine run`."; "<machine-id> (required): Machine identifier argument for `machine update`."; "--app <app-name>: Application name; the run command source lists the app flag."; "Docs conflict: The run command source page is on master, newer than v0.4.27; it is used only for the `<image>` argument, not for the new flag behavior."

### flyctl machine wait waits for a machine state (2026-03-09)
- slug: flyctl-machine-wait-waits-for-a-machine-state-b68c8dfedd8f
- score: 0.96

How to use it:

When a CLI workflow needs to wait for a Fly Machine to reach a state, run `fly machine wait <machine-id>`; it waits for `settled` by default. Use `--state <state>` to select a target and `--wait-timeout <duration>` to set the timeout.

Examples:

```
fly machine wait <machine-id>
```

```
fly machine wait <machine-id> --state <state>
```

```
fly machine wait <machine-id> --state <state> --wait-timeout <duration>
```

- why_it_matters: Wait for a machine to reach a target state or settle during a CLI workflow.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.20>, <https://github.com/superfly/flyctl/pull/4765>, <https://github.com/superfly/flyctl/blob/v0.4.20/internal/command/machine/wait.go>
- gotchas: "Version: v0.4.20"; "machine-id: Optional positional machine ID; command allows zero or one argument and selects a machine when omitted."; "--state: Machine state to wait for; defaults to `settled`."; "--wait-timeout: Duration to wait for the machine to reach the requested state; defaults to 5 minutes. Shorthand: `-w`."; "Prerequisite: Requires an authenticated flyctl session."

### flyctl certificates use the Machines API with custom certificate uploads and domain ownership verification (2026-02-12)
- slug: flyctl-certificates-use-the-machines-api-with-custom-certificate-uploads-and-dom-8f01b1631cf2
- score: 0.95

How to use it:

When managing an app certificate, use `fly certs` commands. Import a custom PEM certificate and key with `import`; use `setup` for DNS instructions and `check` after adding the ownership record.

Examples:

```
fly certs import <hostname> -a <app> --fullchain <path/to/fullchain.pem> --private-key <path/to/private-key.pem>
```

```
fly certs setup <hostname> -a <app>
```

```
fly certs check <hostname> -a <app>
```

- why_it_matters: Manage certificates for an application, including uploading a custom certificate or verifying domain ownership.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.11>, <https://github.com/superfly/flyctl/pull/4739>, <https://github.com/superfly/flyctl/blob/v0.4.11/internal/command/certificates/root.go>
- gotchas: "Version: v0.4.11"; "<hostname> (required): Hostname for the certificate."; "-a, --app <app>: Application name; the command requires an app name, which may come from app configuration instead."; "--fullchain <path> (required): Path to the certificate chain file in PEM format."; "--private-key <path> (required): Path to the private key file in PEM format."; "Prerequisite: The certificate import command requires an authenticated Fly session and an app name."; "Prerequisite: Provide the certificate chain and private key in PEM format. Domain ownership must be verified through DNS before the imported certificate becomes active."; "Certificates are primarily serviced through the Machines API rather than GraphQL."; "The DNS entry can verify domain ownership in certain circumstances."

### flyctl machine supports --swap-size (2026-02-10)
- slug: flyctl-machine-supports-swap-size-fab655d9bef5
- score: 0.93

How to use it:

When configuring a machine with `flyctl` v0.4.9, set a positive swap size with `fly machine run --swap-size <size> <image>`. The size accepts a number in MB or a human-readable value such as `512mb` or `1gb`.

Examples:

```
fly machine run --swap-size <size> <image>
```

- why_it_matters: Set the swap size when configuring a machine.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.9>, <https://github.com/superfly/flyctl/blob/v0.4.9/internal/command/machine/run.go>
- gotchas: "Version: v0.4.9"; "--swap-size <size>: Swap size in MB; accepts a plain number in MB or a human-readable size such as `512mb` or `1gb`. If specified, it must be greater than zero."; "<image> (required): Image or path argument for `machine run`."

### flyctl mpg attach tracks app attachments to MPG clusters (2026-01-08)
- slug: flyctl-mpg-attach-tracks-app-attachments-to-mpg-clusters-e56e363cb016
- score: 0.95

How to use it:

When connecting an app to a Managed Postgres cluster, run `fly mpg attach` to add a connection secret and create the attachment record. Use `fly mpg attach list` to verify attached app names; use `fly mpg detach` to remove the attachment while retaining the secret.

Examples:

```
fly mpg attach <CLUSTER_ID> --app <APP_NAME>
```

```
fly mpg detach <CLUSTER_ID> --app <APP_NAME>
```

- why_it_matters: When connecting an app to a managed Postgres cluster, attach the cluster to the app and verify its attachments.
- before: Previously `mpg attach` created a secret and deployed; it did not create an explicit database connection record between the cluster and app.
- sources: <https://github.com/superfly/flyctl/releases/tag/v0.4.2>, <https://github.com/superfly/flyctl/pull/4717>, <https://github.com/superfly/flyctl/blob/v0.4.2/internal/command/mpg/attach.go>, <https://github.com/superfly/flyctl/blob/v0.4.2/internal/command/mpg/detach.go>
- gotchas: "Version: v0.4.2"; "<CLUSTER_ID>: Managed Postgres cluster ID; when omitted, the command prompts for a cluster."; "--app <APP_NAME> (required): Select the app to attach or detach; the command requires an app name."; "--variable-name <NAME>: Secret environment variable name to add to the app; defaults to `DATABASE_URL`."; "--database, -d <NAME>: Database to connect to; when omitted, an interactive session prompts for selection."; "--username, -u <NAME>: Database user to connect as; when omitted, an interactive session prompts for selection."; "Prerequisite: A Fly.io authenticated session is required."; "Prerequisite: The app and cluster must belong to the same organization."; "`mpg detach` removes the attachment but does not remove the secret."