Fly.io CLI

Fly.io CLI cheatsheet — launch, deploy, scale, debug apps. fly launch, fly deploy, fly logs, fly ssh console, fly secrets set. Full flyctl reference.

8 min read

What it is

The Fly.io CLI is a command-line interface for deploying, managing, and inspecting applications on the Fly.io platform. You reach for it when you need to get your code running on Fly.io, interact with your running apps, or configure your Fly.io resources.

Installation

Linux

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

macOS

brew install flyctl

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

Windows

Download the installer from fly.io/docs/getting-started/installing-flyctl/ or use Scoop:

scoop install flyctl

After installation, you need to log in to your Fly.io account:

flyctl auth login

This will open a browser window for authentication.

Core Concepts

App: A deployed instance of your application on Fly.io. Apps are identified by a unique name.
Machines: The underlying compute instances that run your containers on Fly.io. You can have multiple machines for a single app for redundancy or scaling.
Volumes: Persistent storage attached to machines. Volumes retain data even if the machine is replaced or restarted.
Secrets: Sensitive information like API keys or database passwords that can be securely injected into your application’s environment.
Regions: Geographic locations where your apps and machines can be deployed. Fly.io has a global network of regions.
Fly Apps Platform (FAP): The core infrastructure and services that power Fly.io deployments.

Commands / Usage

App Creation & Deployment

Initialize a new app:
```
flyctl launch
```
This command prompts you to choose a name for your app, select a region, and often detects your application’s language and framework to suggest a Dockerfile and configuration.
Deploy an existing app:
```
flyctl deploy
```
Builds a new Docker image from your current directory (or specified Dockerfile) and deploys it to your app.
Deploy a specific image:
```
flyctl deploy -a my-cool-app --image sven/my-app:latest
```
Deploys a pre-built Docker image to your app.
Set the default app for the current directory:
```
flyctl alias add my-cool-app
```
Associates the current directory with a specific Fly.io app, so you can run flyctl deploy without specifying -a my-cool-app.
Create a new app from scratch:
```
flyctl apps create --name my-new-app --regionams
```
Creates a new, empty app named my-new-app in the Amsterdam region.
List your apps:
```
flyctl apps list
```
Displays all Fly.io applications associated with your account.
Destroy an app:
```
flyctl apps destroy --app my-old-app
```
Permanently deletes an app and all its associated resources. Use with extreme caution.

Managing Machines

List machines for an app:
```
flyctl machine list -a my-cool-app
```
Shows all machines running for a given app.

Start a machine:

flyctl machine start <machine-id> -a my-cool-app

Starts a stopped machine.

Stop a machine:

flyctl machine stop <machine-id> -a my-cool-app

Stops a running machine.

Restart a machine:

flyctl machine restart <machine-id> -a my-cool-app

Restarts a machine.

Delete a machine:

flyctl machine delete <machine-id> -a my-cool-app

Deletes a machine.

Create a new machine:

flyctl machine run "nginx" --image nginx:latest -a my-nginx-app --region lhr --name nginx-web --volume app-data:rw

Creates and starts a new machine with a specified image, region, name, and volume.

Update a machine’s configuration:
```
flyctl machine update <machine-id> -a my-cool-app --memory 512
```
Changes the memory allocation for a specific machine.

Networking & Routing

Display app’s public IP addresses:
```
flyctl ips list -a my-cool-app
```
Shows the public IPv4 and IPv6 addresses assigned to your app.
Allocate a new public IP address:
```
flyctl ips allocate-v4 -a my-cool-app
```
Requests a new public IPv4 address for your app.
Set up a custom domain:
```
flyctl certs create example.com -a my-cool-app
```
Initiates the process for adding a custom domain (and obtaining an SSL certificate) to your app.
List certificates:
```
flyctl certs list -a my-cool-app
```
Shows existing SSL certificates for your app.

Secrets Management

Set a secret:
```
flyctl secrets set MY_API_KEY=abcdef12345 -a my-cool-app
```
Adds or updates a secret for your app. The value is encrypted.
Set multiple secrets from a file:
```
flyctl secrets import .env -a my-cool-app
```
Imports secrets from a .env file. Each line should be KEY=VALUE.
List secrets:
```
flyctl secrets list -a my-cool-app
```
Displays the names of the secrets configured for your app (values are not shown for security).

Unset a secret:

flyctl secrets unset MY_API_KEY -a my-cool-app

Removes a secret from your app.

Volumes (Persistent Storage)

List volumes:
```
flyctl vol list -a my-cool-app
```
Shows all persistent volumes attached to your app.
Create a volume:
```
flyctl vol create my-data-volume -a my-cool-app --region lhr --size 10
```
Creates a new volume named my-data-volume in the lhr region with a size of 10GB.
Attach a volume to a machine:
```
flyctl machine update <machine-id> -a my-cool-app --volume my-data-volume:rw
```
Attaches an existing volume named my-data-volume to a machine with read-write access.

Detach a volume from a machine:

flyctl machine update <machine-id> -a my-cool-app --volume my-data-volume:

Detaches a volume.

Delete a volume:
```
flyctl vol delete <volume-id> -a my-cool-app
```
Deletes a persistent volume. Data will be lost.

Logging & Debugging

View logs for an app:
```
flyctl logs -a my-cool-app
```
Streams logs from all machines running for your app.
View logs for a specific machine:
```
flyctl logs -a my-cool-app -m <machine-id>
```
Streams logs only from a particular machine.
Execute a command inside a running machine:
```
flyctl ssh console -a my-cool-app
```
Opens an interactive SSH session to one of your app’s machines.
Run a one-off command in a machine:
```
flyctl ssh console -a my-cool-app --command "ls -l /app"
```
Executes a single command on a machine and exits.
Attach to a running application’s process:
```
flyctl attach -a my-cool-app
```
Connects to the primary process of your app, useful for debugging or inspection.

Configuration & State

Display app configuration:
```
flyctl status -a my-cool-app
```
Shows the current status of your app, including machines, releases, and routing.
View app configuration file:
```
flyctl config display -a my-cool-app
```
Shows the fly.toml configuration for your app as managed by Fly.io.
Export app configuration:
```
flyctl config export -a my-cool-app > fly.prod.toml
```
Exports the current app configuration to a local file.
Import app configuration:
```
flyctl config import fly.staging.toml -a my-staging-app
```
Imports configuration from a local file to an app.
List available regions:
```
flyctl regions list
```
Shows all regions where you can deploy applications.

Common Patterns

Deploying a web app from a local directory:

# Ensure you have a Dockerfile in your current directory
# Or run 'flyctl launch' to generate one
flyctl deploy

Connecting to a database from your app (using secrets):

# Set your database credentials as secrets
flyctl secrets set DB_USER=myuser -a my-app
flyctl secrets set DB_PASSWORD=mypassword -a my-app
flyctl secrets set DB_HOST=somewhere.fly.dev -a my-app

# Your application code reads these environment variables.

Running a background worker alongside a web service:

# In your fly.toml, define multiple services
# [services.concurrency]
#   type = "connections"
#   hard_limit = 25
#   soft_limit = 20
#
# [[services.processes]]
#   type = "web"
#   port = 8080
#
# [[services.processes]]
#   type = "worker"
#   cmd = ["/app/worker"] # Command to start your worker process

flyctl deploy

Attaching a persistent volume for data:

# Create a volume
flyctl vol create my-app-data -a my-app --region lhr --size 5
# Attach it to your app's machines (fly.toml or via machine update)
flyctl machine update <machine-id> -a my-app --volume my-app-data:rw

Executing a database migration:

# Ensure your migration command is defined in your app's Dockerfile or entrypoint
# Then run it as a one-off command or a specific machine type
flyctl ssh console -a my-app --command "/app/bin/migrate"

Accessing logs and debugging a running service:

# Stream logs in real-time
flyctl logs -a my-app

# Open an interactive shell to inspect the filesystem or run commands
flyctl ssh console -a my-app

Gotchas

flyctl deploy vs. flyctl machine run: deploy is for updating your application image and configuration. machine run is for creating a single, ephemeral or persistent machine with a specific image and command, often used for one-off tasks or simple services.
Volume Mounting: Volumes are mounted at a specific path within the container’s filesystem. You need to ensure your application is configured to use this path for persistent data. The mount point is typically defined in fly.toml or specified during machine creation/update.
Secrets are environment variables: While managed securely by Fly.io, secrets are injected into your application as environment variables. Make sure your application code reads them correctly.
App Names vs. Machine IDs: Apps are the top-level resource. Machines are the individual compute instances running your app. Many commands require specifying the app name (-a) and sometimes a specific machine ID.
Region Defaults: If you don’t specify a region for a new app or machine, Fly.io will choose a default region for you. It’s usually best to explicitly choose your desired region.
Downtime during Deploy: Deployments can involve rolling updates, but for critical applications, consider strategies like blue/green deployments or read-only modes during updates if zero downtime is paramount.
fly.toml Configuration: Many settings (volumes, ports, secrets, environment variables) can be configured directly in your fly.toml file. Changes to fly.toml usually require a flyctl deploy to take effect.
Resource Limits: Be mindful of the default resource limits (CPU, memory, disk) for your app and machines. You can increase these in your fly.toml or using flyctl machine update.