Deploy Web Apps Using the Galaxy CLI

Love working in the terminal? The Galaxy CLI lets you deploy Web Apps, manage environment variables, and handle your entire workflow without opening a browser. Four commands and you're live.

Meteor Apps Use Meteor CLI

Galaxy CLI works for Web Apps only. To deploy Meteor apps from the command line, use the Meteor CLI instead. Galaxy CLI supports Node.js, Next.js, AdonisJS, and Python Web Apps.

Quick Start

npm install -g @galaxy-cloud/cli
galaxy login
galaxy init
galaxy deploy

That's it. Your app is running on Galaxy.

Installation

Install the CLI globally so you can run galaxy from anywhere:

npm install -g @galaxy-cloud/cli

Requires Node.js 18 or higher.

Don't want to install anything? Run commands directly with npx:

npx @galaxy-cloud/cli login
npx @galaxy-cloud/cli init
npx @galaxy-cloud/cli deploy

Great for trying things out or ensuring you always have the latest version.

Your First Deployment

Authenticate

galaxy login

This opens your browser for OAuth authentication. Pick your account or organization, complete the flow, and you're in.

Want to see your current context? Run galaxy whoami to check which account you're deploying to.

Initialize Your Project

galaxy init

The CLI walks you through setup interactively:

App name: What you want to call your app (lowercase letters, numbers, hyphens only, minimum 3 characters)
App type: Node.js, Next.js, AdonisJS, or Python
Runtime version: Depends on your app type (e.g., Node.js 18/20/22, Python 3.11/3.12)
Plan: Select based on your needs (free tier available)
Region: Where to deploy (paid plans get region selection, free tier uses US)
Subdomain: Your app's URL prefix (validated for availability)
Container size: Memory and CPU allocation
Install command: Usually npm install or pip install (optional)
Build command: Usually npm run build (optional)
Start command: How to start your app (required)
Health check path: An endpoint Galaxy pings to verify your app is running (optional)

Don't worry about getting everything perfect. You can change most settings later.

Paid Plans Require Payment Method

If you select a paid plan, the CLI will prompt you to add a payment method via the dashboard before continuing.

Next.js Apps Need Standalone Mode

Next.js apps require output: 'standalone' in your next.config.ts or next.config.js. The CLI validates this automatically and will show an error if it's missing.

Deploy

galaxy deploy

The CLI packages your code (respecting .galaxyignore), calculates a checksum, uploads the archive, builds a Docker image, and deploys to Galaxy. You'll see build and deploy logs streaming in real-time as each phase happens.

Each deployment creates a new version (v1, v2, v3...). Your app updates with zero downtime.

You're Live

Done. Every future deploy is just galaxy deploy from your project directory.

Configuration Files

The CLI uses three config files with different purposes.

`.galaxy/config.json` (Private)

Links your directory to a Galaxy app. Created automatically during galaxy init or galaxy link. Never commit this to Git.

{
  "appId": "your-app-id-here"
}

`galaxy.json` (Shareable)

Your deployment configuration. Optional, and safe to commit so your team shares the same settings.

{
  "commands": {
    "install": "npm install",
    "build": "npm run build",
    "start": "npm start"
  },
  "health": {
    "path": "/health"
  },
  "deploy": {
    "rootDirectory": "./"
  }
}

No galaxy.json? Galaxy uses defaults from your app settings.

Backend Defaults

Some settings like region, plan, and container size live on the backend. Change those through the dashboard or during galaxy init.

`.galaxyignore` (Optional)

Exclude files from deployments, just like .gitignore:

node_modules/
.git/
*.log
.env

Default patterns apply automatically even without this file:

.git/**
node_modules/**
.galaxyignore
galaxy.json
*.log
.DS_Store
Thumbs.db

Commands

Authentication

Command	What it does
`galaxy login`	Authenticate via browser (OAuth Device Flow)
`galaxy logout`	Clear local credentials
`galaxy whoami`	Show current user, deployment context, and available organizations

Run galaxy login again to switch between personal accounts and organizations. Your credentials are stored in ~/.config/galaxy/auth.json.

Project Setup

Command	What it does
`galaxy init`	Create a new app and link your directory
`galaxy link <app-id>`	Link to an existing app
`galaxy link <app-id> --with-config`	Link and pull deployment config from backend
`galaxy unlink`	Disconnect directory from linked app (doesn't delete the app)
`galaxy config`	Show current configuration and validate files

When you run galaxy link, the CLI fetches your app details and shows you the app name, region, and current status. It also updates your .gitignore automatically.

Finding Your App ID

Grab it from your dashboard URL: https://beta.galaxycloud.app/{account}/{region}/apps/{appId}/overview

Deployment

Command	What it does
`galaxy deploy`	Deploy your application with real-time log streaming
`galaxy deploy --path <dir>`	Deploy from a specific directory
`galaxy deploy --env <file>`	Deploy with environment variables from file
`galaxy deploy --detach`	Fire-and-forget (skip log streaming)

The maximum archive size is 100MB. Use .galaxyignore to exclude large files.

Logs

Command	What it does
`galaxy logs --deployment <id>`	View build and deploy logs for a specific deployment

The logs command replays historical logs and automatically tails in-progress deployments. You'll see both build phase (installing dependencies, building Docker image) and deploy phase (configuring, deploying to cloud) logs.

Environment Variables

Galaxy uses a staging workflow. Make changes, then deploy them when ready. This lets you batch updates before triggering a restart.

Command	What it does
`galaxy variables`	List all variables (values masked)
`galaxy variables --env <file>`	Import variables from a .env file
`galaxy variables:set KEY VALUE`	Stage a variable change
`galaxy variables:unset KEY`	Stage a variable deletion
`galaxy variables:deploy`	Deploy all pending changes
`galaxy variables:status`	Check for pending changes
`galaxy variables:diff <deployment-id>`	See what changed in a specific deployment

Changes Require Deployment

Setting or unsetting variables only stages the change. Run galaxy variables:deploy to apply it.

Key Format Requirements

Variable keys must start with an uppercase letter or underscore, and contain only UPPERCASE letters, numbers, and underscores (e.g., DATABASE_URL, API_KEY_V2, _PRIVATE_VAR). No spaces, dashes, or special characters allowed.

Quick Config Change

Need to rotate an API key? Two commands:

galaxy variables:set API_KEY new_secret_value
galaxy variables:deploy

No code upload, no build. Just a fast restart with the new value.

`variables:deploy` vs `galaxy deploy`

What's the difference?

galaxy variables:deploy: Config-only. Fast. No code upload or build. Just restarts with new environment variables. Triggers a rolling restart if your app is running.

galaxy deploy: Full deployment. Uploads code, builds Docker image, deploys. Use when your code changed.

If you're deploying code anyway, you can combine both:

galaxy deploy --env .env.production

This uploads your code and imports variables in one operation.

Import from File

galaxy variables --env .env.production
galaxy variables:deploy

View Deployment Diff

See what variables changed in a specific deployment:

galaxy variables:diff 550e8400-e29b-41d4-a716-446655440000

Shows added, updated, and deleted variables for that deployment.

Team Collaboration

When teammates clone your repository, they need to link their local directory to the existing app.

git clone https://github.com/your-team/your-app.git
cd your-app
galaxy link <app-id>
galaxy deploy

Add --with-config to also pull the latest galaxy.json from the backend:

galaxy link <app-id> --with-config

Config File Sharing

The galaxy.json file can be committed for team sharing. The .galaxy/config.json file is gitignored and specific to each machine.

Connecting CLI Apps to Git (Push to Deploy)

Started with the CLI but want automatic deployments from GitHub? You can connect your CLI-created app to Git at any time.

When you open a CLI-created app in the Galaxy dashboard for the first time, you'll see a modal asking how you want to deploy going forward:

Option 1: Continue Using CLI

Keep using galaxy deploy from your terminal. Nothing changes. This is great if you prefer manual control over when deployments happen.

Option 2: Switch to Git Deployments

Connect your app to a GitHub repository and enable Push to Deploy. Every push to your deploy branch triggers an automatic deployment.

For detailed setup instructions on connecting your app to Git, see the Web Apps Push to Deploy guide.

Galaxy imports your existing CLI configuration, so the setup process is straightforward. Once connected, pushing to your deploy branch triggers automatic builds and deployments.

Use Both Methods

Switching to Git doesn't disable the CLI. You can still run galaxy deploy for one-off deployments or when you want to deploy without pushing to Git.

Migrating from Old Format

Have an old galaxy.json with appId, app, and container fields? Just run:

galaxy deploy

The CLI detects the old format and offers to migrate automatically. It moves appId to .galaxy/config.json, keeps only deployment config in galaxy.json, and updates your .gitignore.

Troubleshooting

Command Reference

Here's the complete list of all available commands:

# Authentication
galaxy login                              # Authenticate with Galaxy
galaxy logout                             # Clear local credentials
galaxy whoami                             # Show current user and context

# Project Management
galaxy init                               # Create new app and link directory
galaxy link <app-id>                      # Link to existing app
galaxy link <app-id> --with-config        # Link and pull galaxy.json
galaxy unlink                             # Disconnect from linked app
galaxy config                             # Show and validate configuration

# Deployment
galaxy deploy                             # Deploy with log streaming
galaxy deploy --path <dir>                # Deploy from specific directory
galaxy deploy --env <file>                # Deploy with env vars from file
galaxy deploy --detach                    # Deploy without log streaming

# Environment Variables
galaxy variables                          # List all variables
galaxy variables --env <file>             # Import from .env file
galaxy variables:set KEY VALUE            # Stage a variable change
galaxy variables:unset KEY                # Stage a variable deletion
galaxy variables:deploy                   # Deploy pending changes
galaxy variables:status                   # Check for pending changes
galaxy variables:diff <deployment-id>     # Show deployment diff

# Logs
galaxy logs --deployment <id>             # View deployment logs

Deploy Web Apps Using the Galaxy CLI

Quick Start

Installation

Your First Deployment

Authenticate

Initialize Your Project

Deploy

Configuration Files

`.galaxy/config.json` (Private)

`galaxy.json` (Shareable)

`.galaxyignore` (Optional)

Commands

Authentication

Project Setup

Deployment

Logs

Environment Variables

Quick Config Change

`variables:deploy` vs `galaxy deploy`

Import from File

View Deployment Diff

Team Collaboration

Connecting CLI Apps to Git (Push to Deploy)

Migrating from Old Format

Troubleshooting

Command Reference

What's Next?

Push to Deploy

Environment Variables

On this page

Deploy Web Apps Using the Galaxy CLI

Authentication fails

Archive too large

Variables not updating

Health check failed

Invalid variable key

No app linked to directory

Build logs not streaming

Next.js deployment fails

Subdomain not available

Paid plan requires payment method

Push to Deploy

Environment Variables

On this page