NuxFly logoNuxFly

CLI Commands

The @nuxfly/cli provides powerful commands for deploying and managing your Nuxt applications on Fly.io.

Installation

npm i @nuxfly/cli

Authentication

Before using the CLI, make sure you're authenticated with Fly.io:

fly auth login

Commands Overview

The CLI provides several commands for different stages of your deployment workflow:

launch

Create and configure a new Fly.io application with database and storage

deploy

Deploy your application to Fly.io with automatic bucket creation

generate

Generate deployment files (Dockerfile, fly.toml) without deploying

studio

Open Drizzle Studio with secure tunnel to your database

Global Options

All commands support these global options:

  • --verbose, -v - Enable verbose logging
  • --config - Path to fly.toml config file
  • --app, -a - Fly app name

launch

Create a new Fly.io application with integrated database and storage.

nuxfly launch [options]

Options

  • --name - App name (if not provided, Fly.io will generate one)
  • --region - Region to deploy to (e.g., ord, fra, nrt)
  • --no-deploy - Skip deployment after launch (default: true)
  • --size - Size in GB for SQLite volume (default: 1)

Multi-Environment Support

Creates or uses environment-specific configuration files based on NUXFLY_ENV:

  • NUXFLY_ENV=prod (or unset) → Creates fly.toml
  • NUXFLY_ENV=staging → Creates fly.staging.toml
  • NUXFLY_ENV=development → Creates fly.development.toml

What it does

Creates Fly.io App - Initializes a new application on Fly.io

Sets up SQLite Database - Creates a persistent volume for SQLite with Litestream backup

Configures S3 Storage - Creates public and private S3-compatible buckets

Generates Files - Creates Dockerfile and environment-specific fly.toml in .nuxfly/ directory

Sets Environment Variables - Configures database and storage credentials

Example

# Launch production app (creates fly.toml)
nuxfly launch --name my-nuxt-app --region ord

# Launch staging app (creates fly.staging.toml)
export NUXFLY_ENV=staging
nuxfly launch --name my-app-staging --region ord

# Launch with larger database volume
nuxfly launch --size 5
The launch command creates a .nuxfly/ directory in your project with all deployment files. This keeps your project root clean while maintaining all necessary configuration.

deploy

Deploy your application to Fly.io with automatic infrastructure setup.

nuxfly deploy [options]

Options

  • --strategy - Deployment strategy (e.g., rolling, immediate)
  • --build - Build the application before deploying (default: false)

Multi-Environment Support

Uses the appropriate configuration file based on NUXFLY_ENV:

  • If only fly.toml exists: Uses fly.toml (no NUXFLY_ENV required)
  • If fly.*.toml files exist: Requires NUXFLY_ENV to select the correct file

What it does

Validates Configuration - Ensures all required files and settings are present

Creates Missing Buckets - Automatically creates any missing S3 buckets

Builds Application - Optionally builds your Nuxt app before deployment

Deploys to Fly.io - Pushes your application using the environment-specific configuration

Example

# Deploy to production (if only fly.toml exists)
nuxfly deploy

# Deploy to specific environment (when multiple fly.*.toml files exist)
NUXFLY_ENV=staging nuxfly deploy --build
NUXFLY_ENV=prod nuxfly deploy --strategy rolling

generate

Generate deployment files without deploying.

nuxfly generate [options]

Options

  • --build - Build the application before generating files (default: false)

What it does

Creates Dockerfile - Generates optimized Dockerfile for Nuxt applications

Creates fly.toml - Generates Fly.io configuration with proper settings

Sets up Environment - Configures environment variables for database and storage

Generated Files

The command creates these files in the .nuxfly/ directory:

  • Dockerfile - Multi-stage Docker build for optimal image size
  • fly.toml - Fly.io application configuration
  • .dockerignore - Docker ignore patterns

Example

# Generate files only
nuxfly generate

# Generate with build step
nuxfly generate --build

studio

Open Drizzle Studio with secure tunnel to your production database.

nuxfly studio [options]

Options

  • --port - Local port for studio (default: 4983)
  • --remote-port - Remote tunnel port (default: 5432)

What it does

Creates Secure Tunnel - Establishes encrypted connection to your database

Launches Drizzle Studio - Opens the database management interface

Provides Access - Allows you to browse and edit your production data safely

Requirements

  • drizzle-kit must be installed in your project
  • Valid drizzle.config.ts configuration file
  • Deployed application with database

Example

# Open studio on default port
nuxfly studio

# Use custom port
nuxfly studio --port 3000

# Custom tunnel configuration
nuxfly studio --port 4000 --remote-port 5433
Be careful when editing production data through Studio. Always backup your database before making significant changes.

import

Import existing Fly app configuration.

nuxfly import [options]

Options

  • --app - App name to import

What it does

Downloads Configuration - Retrieves existing fly.toml from Fly.io

Saves Locally - Stores configuration in environment-specific fly.toml (e.g., fly.toml, fly.staging.toml)

Validates Setup - Ensures all required settings are present

Example

# Import specific app
nuxfly import --app my-existing-app

proxy

Proxy unknown commands to flyctl with app context.

The CLI automatically proxies any unrecognized commands to the Fly.io CLI (flyctl) with the correct app context.

Example

# These commands are proxied to flyctl:
nuxfly logs
nuxfly status
nuxfly ssh console
nuxfly scale show

This allows you to use any flyctl command while maintaining the context of your nuxfly-managed application.

Configuration

Project Configuration

The CLI looks for configuration in several places:

fly.toml (or fly.staging.toml, etc.) - Generated environment-specific Fly.io configuration

.nuxfly/Dockerfile - Generated Docker configuration

Environment variables

Command-line arguments

Environment Variables

You can override configuration using environment variables:

# App configuration
FLY_APP_NAME=my-app
FLY_REGION=ord

# Database
NUXFLY_DB_URL=file:.data/db.sqlite

# Storage
NUXFLY_PUBLIC_BUCKET_NAME=my-public-bucket
NUXFLY_PRIVATE_BUCKET_NAME=my-private-bucket

Workflow Examples

Initial Setup

# 1. Create and configure new app
nuxfly launch --name my-blog --region ord

# 2. Deploy the application
nuxfly deploy --build

# 3. Check status
nuxfly status

# 4. View logs
nuxfly logs

Development Workflow

# Make changes to your app...

# Deploy updates
nuxfly deploy

# Check database
nuxfly studio

# Monitor logs
nuxfly logs --follow

Database Management

# Open database studio
nuxfly studio

# SSH into app for direct access
nuxfly ssh console

# Check app status
nuxfly status

Troubleshooting

Common Issues

Debug Mode

Enable verbose logging for detailed output:

nuxfly --verbose deploy

Getting Help

Get help for any command:

nuxfly --help
nuxfly launch --help
nuxfly deploy --help

Advanced Usage

Custom Dockerfile

You can customize the generated Dockerfile by editing .nuxfly/Dockerfile after generation:

# .nuxfly/Dockerfile
FROM node:18-alpine

# Your custom modifications...

Custom fly.toml

Modify the generated fly.toml (or environment-specific file like fly.staging.toml) for advanced configuration:

# fly.toml
[build]
  dockerfile = ".nuxfly/Dockerfile"

[env]
  NODE_ENV = "production"
  # Your custom environment variables...

[[services]]
  internal_port = 3000
  protocol = "tcp"
  # Your custom service configuration...

Multiple Environments

Nuxfly supports multi-environment deployments using NUXFLY_ENV and environment-specific configuration files:

File naming convention:

  • fly.toml - Production (default, or when NUXFLY_ENV=prod)
  • fly.staging.toml - Staging (when NUXFLY_ENV=staging)
  • fly.development.toml - Development (when NUXFLY_ENV=development)

When NUXFLY_ENV is required:

  • Single environment (only fly.toml): NUXFLY_ENV is optional (defaults to prod)
  • Multi-environment (has fly.*.toml files): NUXFLY_ENV is required

Setup and deploy:

# Create staging environment
export NUXFLY_ENV=staging
nuxfly launch --name myapp-staging --region ord

# Create production environment
export NUXFLY_ENV=prod  # or omit if only fly.toml exists
nuxfly launch --name myapp-prod --region ord

# Deploy to environments
NUXFLY_ENV=staging nuxfly deploy
NUXFLY_ENV=prod nuxfly deploy  # or just: nuxfly deploy (if there are no other fly.*.toml files)
Read more in Guide.
Read more in Module.

Nuxt Module

The @nuxfly/core module provides runtime composables for database and storage access in your Nuxt application.