Fly.io (flyctl) CLI

Operate Fly.io apps safely and repeatably with flyctl.

Common tasks

• •Deploy: fly deploy / fly deploy --remote-only
• •Logs: fly logs -a <app>
• •SSH / run commands: fly ssh console -a <app> -C "…"
• •Secrets: fly secrets list/set -a <app>
• •Postgres: fly postgres list/connect/db create/attach
• •GitHub Actions deploys / PR previews

Defaults / safety

• •Prefer read-only commands first: fly status, fly logs, fly config show, fly releases, fly secrets list.
• •Do not run state-changing Fly.io commands without explicit user approval (deploy/scale, secrets set/unset, volume/db create/drop, app destroy, attach/detach).
  • •Read-only actions are OK without approval.
  • •Destructive actions (destroy/drop) always require explicit approval.
• •When debugging, classify the failure as: build/packaging vs runtime vs platform.

Quick start (typical deploy)

From the app repo directory:

1. •Confirm which app you’re targeting

• •fly app list
• •fly status -a <app>
• •Check fly.toml for app = "..."

1. •Deploy

• •fly deploy (default)
• •fly deploy --remote-only (common when local docker/build env is inconsistent)

1. •Validate

• •fly status -a <app>
• •fly logs -a <app>
• •fly open -a <app>

Debugging deploy/build failures

Common checks

• •fly deploy --verbose (more build logs)
• •If using Dockerfile builds: verify Dockerfile Ruby/version and Gemfile.lock platforms match your builder OS/arch.

Rails + Docker + native gems (nokogiri, pg, etc.)

Symptoms: Bundler can’t find a platform gem like nokogiri-…-x86_64-linux during build.

Fix pattern:

• •Ensure Gemfile.lock includes the Linux platform used by Fly’s builder (usually x86_64-linux).
  • •Example: bundle lock --add-platform x86_64-linux
• •Ensure Dockerfile’s Ruby version matches .ruby-version.

(See references/rails-docker-builds.md.)

Logs, SSH, console

• •Stream logs:
  • •fly logs -a <app>
• •SSH console:
  • •fly ssh console -a <app>
• •Run a one-off command:
  • •fly ssh console -a <app> -C "bin/rails db:migrate"

Secrets / config

• •List secrets:
  • •fly secrets list -a <app>
• •Set secrets:
  • •fly secrets set -a <app> KEY=value OTHER=value
• •Show config:
  • •fly config show -a <app>

Fly Postgres basics

Identify the Postgres app

• •fly postgres list

Attach Postgres to an app

• •fly postgres attach <pg-app> -a <app>

Create a database inside the cluster

• •fly postgres db create <db_name> -a <pg-app>
• •fly postgres db list -a <pg-app>

Connect (psql)

• •fly postgres connect -a <pg-app>

GitHub Actions deploys / previews

• •For production CD: use Fly’s GitHub Action (superfly/flyctl-actions/setup-flyctl) and run fly deploy (often with --remote-only).
• •For PR previews:
  • •Prefer one preview app per PR and one database per PR inside a shared Fly Postgres cluster.
  • •Automate create/deploy/comment on PR; destroy on close.

(See references/github-actions.md.)

Bundled resources

• •references/rails-docker-builds.md: Rails/Docker/Fly build failure patterns + fixes.
• •references/github-actions.md: Fly deploy + preview workflows.
• •scripts/fly_app_from_toml.sh: tiny helper to print the Fly app name from fly.toml.