Fly.io (flyctl) CLI

Operate Fly.io apps safely and repeatably with flyctl.

Defaults / safety

• - Prefer read-only commands first: fly status, fly logs, fly config show, fly releases, fly secrets list.
• Do not edit/modify Fly.io apps, machines, secrets, volumes, or databases without your human’s explicit approval.

- Read-only actions are OK without approval. - Destructive actions (destroy/drop) always require explicit approval.

• - When debugging builds, capture the exact error output and determine whether it’s a:

- build/packaging issue (Dockerfile, Gemfile.lock platforms, assets precompile) - runtime issue (secrets, DB, migrations) - platform issue (regions, machines, health checks)

Quick start (typical deploy)

From the app repo directory:

1) Confirm which app you’re targeting

• - INLINECODE6
• INLINECODE7
• Check fly.toml for INLINECODE9

2) Validate / inspect (read-only)

• - INLINECODE10
• INLINECODE11
• INLINECODE12

(Deploys are in High-risk operations below and require explicit user approval.)

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 & config (read-only)

• - Stream logs:

- fly logs -a <app>

• - Show config:

- fly config show -a <app>

• - List secrets (names only):

- INLINECODE22

High-risk operations (ask first)

These commands can execute arbitrary code on servers or mutate production state.
Only run them when the user explicitly asks you to.

• - Deploy:

- fly deploy / fly deploy --remote-only

• - SSH exec / console:

- fly ssh console -a <app> -C "<command>"

• - Secrets changes:

- INLINECODE26

See references/safety.md.

Fly Postgres basics

Identify the Postgres app

• - INLINECODE28

Attach Postgres to an app

• - INLINECODE29

Create a database inside the cluster

• - INLINECODE30
• INLINECODE31

Connect (psql)

• - INLINECODE32

GitHub Actions deploys / previews

• - For production CD: use Fly’s GitHub Action (superfly/flyctl-actions/setup-flyctl) and run flyctl deploy.
• 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/safety.md: safety rules (read-only by default; ask before mutating state).
• INLINECODE37: Rails/Docker/Fly build failure patterns + fixes.
• INLINECODE38: Fly deploy + preview workflows.
• INLINECODE39: tiny helper to print the Fly app name from fly.toml (shell-only; no ruby).