home / skills / openclaw / skills / flyio-cli
This skill helps you deploy, monitor, and securely manage Fly.io apps and Postgres using the flyctl CLI with safety checks.
npx playbooks add skill openclaw/skills --skill flyio-cliReview the files below or copy the command above to add this skill to your agents.
---
name: flyio-cli-public
description: "Use the Fly.io flyctl CLI for deploying and operating apps on Fly.io: deploys (local or remote builder), viewing status/logs, SSH/console, secrets/config, scaling, machines, volumes, and Fly Postgres (create/attach/manage databases). Use when asked to deploy to Fly.io, debug fly deploy/build/runtime failures, set up GitHub Actions deploys/previews, or safely manage Fly apps and Postgres."
---
# 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 = "..."`
2) Deploy
- `fly deploy` (default)
- `fly deploy --remote-only` (common when local docker/build env is inconsistent)
3) 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.
This skill uses the Fly.io flyctl CLI to deploy, operate, and debug apps and Postgres databases on Fly.io. It helps run safe, repeatable commands for deploys (local or remote builder), logs, SSH/console access, secrets/config management, scaling, machines, volumes, and Fly Postgres lifecycle tasks. The skill emphasizes read-only inspection first and requires explicit approval before performing state-changing or destructive operations.
I inspect the target Fly app and environment using read-only flyctl commands like fly status, fly logs, fly config show, and fly secrets list. For deploys I can run fly deploy (local or --remote-only) and validate with fly status, fly logs, and fly open. For Postgres I list, attach, create, and connect to databases with fly postgres commands. I never execute destructive actions (destroy, db drop, detach) without your explicit approval.
Can you perform destructive actions like dropping databases or destroying apps?
No. I will never run destructive actions without your explicit, recorded approval. I will provide the exact flyctl commands and explain consequences before executing anything state-changing.
When should I use --remote-only for deploys?
Use --remote-only when your local build environment (Docker or platform-specific toolchain) is inconsistent with Fly’s builder, or when you want the builder to run the build in Fly’s cloud environment for reproducibility.