CLI Commands Reference¶

Complete reference for Airbase CLI commands

This reference provides detailed documentation for all Airbase CLI commands, their options, and usage patterns.

Installation¶

macOS/Linux¶

curl -fsSL https://console.airbase.tech.gov.sg/dist/install.sh | sh

Windows (PowerShell)¶

iwr https://console.airbase.tech.gov.sg/dist/install.ps1 -useb | iex

Installation Paths¶

macOS/Linux: - Primary: ~/.local/bin/airbase (default if directory exists) - Fallback: /usr/local/bin/airbase (used if ~/.local/bin doesn't exist)

Windows: - Varies by system (installer adds to PATH automatically)

Ensure CLI is in PATH¶

macOS/Linux:

# Check if ~/.local/bin is in PATH
echo $PATH | grep ".local/bin"

# If not, add to shell config (~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

# Reload shell config
source ~/.bashrc  # or source ~/.zshrc

Windows:

The installer should automatically add to PATH. Restart PowerShell/Command Prompt after installation.

Verify Installation¶

airbase version
which airbase  # macOS/Linux
where airbase  # Windows

Other Platforms¶

• CLI Download: https://go.gov.sg/airbase-cli
• Full Documentation: https://go.gov.sg/airbase-docs

Current Version: v1.0.3

Command Structure¶

The Airbase CLI supports two command forms:

Modern syntax (recommended):

airbase [global-flags] [command] [flags]

Legacy syntax (backward compatibility):

airbase [global-flags] container [command] [flags]

Both forms are functionally identical. The legacy container keyword is maintained for backward compatibility with older scripts.

Examples:

# Modern syntax
airbase build
airbase deploy staging -y

# Legacy syntax (still valid)
airbase container build
airbase container deploy staging -y

Global Flags¶

Available for all commands:

Examples:

# Use JSON output format
airbase project list -o json

# Enable verbose logging
airbase deploy --verbose -y

# Use in CI mode
airbase deploy --ci -y

Commands Overview¶

airbase login¶

Authenticate with Airbase to access deployment functionality.

Usage¶

airbase login

Description¶

Opens your default browser to authenticate with Airbase using an interactive verification code flow. After successful authentication, stores credentials locally for subsequent commands.

Interactive Authentication Flow¶

1. Run airbase login in terminal
2. CLI displays a verification code
3. Browser automatically opens to Airbase login page
4. Log in via browser (if not already authenticated)
5. Verify the code in browser matches the code shown in terminal
6. Approve CLI access from browser
7. Credentials are persisted locally on the device
8. CLI confirms successful authentication

Authentication Storage¶

Credentials are stored in: - macOS: ~/Library/Application Support/airbase/ - Linux: ~/.config/airbase/ - Windows: %APPDATA%\airbase\ - Format: Encrypted token file - Scope: Per-user, system-wide

Examples¶

# Interactive login
airbase login

Expected output:

Opening browser for authentication...
Verification code: ABC-123-XYZ
✓ Authentication successful
✓ Credentials saved

Notes¶

• Interactive flow requires both terminal and browser access
• Credentials persist locally - authentication is remembered between sessions
• No command to verify login status; re-run if authentication fails
• For automated/CI/CD environments, consult CI/CD Usage section

Troubleshooting¶

Issue: Browser doesn't open

Manually navigate to the URL shown in the terminal.

Issue: Authentication fails

• Ensure you have access to Airbase
• Check your government credentials
• Verify network connectivity to console.airbase.tech.gov.sg
• If authentication expires, simply run airbase login again

Issue: Authentication errors during deployment

Re-run airbase login to refresh credentials.

airbase configure¶

Interactive configuration tool for creating or updating airbase.json.

Usage¶

airbase configure

Description¶

Launches an interactive prompt to configure your project. Creates or updates airbase.json in the current directory.

Recommended: Use interactive mode (no flags) for reliable configuration.

Interactive Prompts¶

1. Project handle: Select from your available projects
2. Port: Enter application listening port (default: 3000)
3. Instance type: Select instance size (default: nano)

Generated File¶

Creates airbase.json:

{
  "framework": "container",
  "handle": "team-name/project-name",
  "port": 3000,
  "instanceType": "nano"
}

Examples¶

# Run interactive configuration (recommended)
airbase configure

Expected interaction:

? Select your project: runtime/demo
? Port: 3000
? Instance type: nano
✓ Configuration saved to airbase.json

Available Flags (Not Recommended)¶

The command supports flags for non-interactive configuration:

• --handle <string> - Project handle (format: team/project)
• -p, --port <number> - Port number
• --allow-ips <string> - Comma-separated list of allowed IPs/CIDRs
• -i, --inline - Overwrite mode without prompt
• -h, --help - Help for configure

⚠️ Warning: Flags are buggy and unreliable. The command expects all flags to be provided or none at all. Use interactive mode instead.

Notes¶

• Must be authenticated (airbase login) before running
• Creates file in current working directory
• Overwrites existing airbase.json if present
• Interactive mode is stable and recommended

airbase project list¶

Display all projects accessible from your Airbase account.

Usage¶

airbase project list
airbase project list -o json

Description¶

Lists all projects you have access to across all teams. Useful for finding project handles when running airbase configure.

Output Format¶

Table format (default):

project          team
--------------   --------
demo             runtime
my-app           platform
dashboard        analytics

JSON format:

airbase project list -o json

Use Cases¶

• Find project handles before running airbase configure
• Verify access to projects
• Discover available projects in your account
• Combine team and project to form handle: team/project

Examples¶

# List all projects (table format)
airbase project list

# List all projects (JSON format)
airbase project list -o json

# List all projects (plain text)
airbase project list -o plain

Notes¶

• Requires authentication (airbase login)
• Project handle format: team-name/project-name
• Example: From output above, handles would be runtime/demo, platform/my-app, etc.

airbase project get¶

Get detailed information about a specific project.

Usage¶

airbase project get <project-name> --team <team-name>

Arguments¶

Flags¶

Examples¶

# Get project details
airbase project get demo --team runtime

# With different team
airbase project get my-app --team platform

Description¶

Fetches detailed project information including configuration and deployment status.

Notes¶

• Requires authentication (airbase login)
• Both project name and team flag are required
• Use airbase project list to discover available projects and teams

airbase build¶

Build a container image from your Dockerfile.

Usage¶

airbase build [OPTIONS]

Legacy syntax (still valid):

airbase container build [OPTIONS]

Description¶

Builds a container image using Docker locally, then pushes it to the Airbase-managed container registry.

Requirements¶

• Docker must be installed and running
• Dockerfile must exist in current directory (or specify path with -f)
• Must be authenticated (airbase login)
• Dockerfile must follow Airbase platform constraints (non-root user, proper ownership)

Build Process¶

1. Reads Dockerfile from current directory
2. Builds image using local Docker daemon
3. Tags image with Airbase-specific tag
4. Pushes image to Airbase registry
5. Image ready for deployment

Flags¶

Examples¶

# Build with default Dockerfile
airbase build

# Legacy syntax
airbase container build

# Build with custom tag
airbase build -t my-app:v1.0

# Build with custom Dockerfile path
airbase build -f docker/Dockerfile.prod

# Build with build arguments
airbase build --build-arg NODE_ENV=production
airbase build --build-arg A=1 --build-arg B=2

# Build specific stage in multi-stage Dockerfile
airbase build --target production

# Build and push immediately
airbase build -t my-app:latest --push

Expected Output¶

Building container...
[+] Building 45.2s (12/12) FINISHED
 => [internal] load build definition from Dockerfile
 => => transferring dockerfile: 326B
 => [internal] load .dockerignore
 => ...
✓ Build complete
✓ Image pushed to registry

Build Time¶

• First build: 2-5 minutes (downloads base images)
• Subsequent builds: 30 seconds - 2 minutes (uses cache)

When to Build¶

• ✅ Application code changed (JS, Python, etc.)
• ✅ Dependencies changed (package.json, requirements.txt, etc.)
• ✅ Dockerfile modified
• ✅ Static assets need rebuilding
• ❌ Only airbase.json or .env changed (just use airbase deploy)

Caching¶

Docker layer caching is used to speed up builds: - Base images are cached locally - Unchanged layers are reused - Only modified layers are rebuilt

Troubleshooting¶

Issue: Docker not running

Cannot connect to the Docker daemon...

Solution: Start Docker Desktop or Docker service.

Issue: Dockerfile not found

Error: Dockerfile not found

Solution: Run command from directory containing Dockerfile, or use --file flag.

Issue: Build fails

Check Dockerfile syntax and requirements. See Dockerfile Requirements.

airbase deploy¶

Deploy your application to Airbase.

Usage¶

airbase deploy [OPTIONS] [ENVIRONMENT]

Legacy syntax (still valid):

airbase container deploy [OPTIONS] [ENVIRONMENT]

Description¶

Deploys a container image to Airbase, making your application accessible via HTTPS URL.

Arguments¶

Flags¶

Examples¶

Deploy to default environment (production):

airbase deploy -y

Deploy to named environment:

airbase deploy staging -y
airbase deploy development -y
airbase deploy feature-auth -y

Deploy with custom settings:

# Deploy specific image
airbase deploy --image my-app:v1.2.3 -y

# Override port
airbase deploy --port 8080 -y

# Open URL in browser after deployment
airbase deploy staging --open -y

# Write URL to file
airbase deploy -y -o deployment-url.txt

Legacy syntax examples:

# Same commands with legacy syntax
airbase container deploy -y
airbase container deploy staging -y

Deployment Process¶

1. CLI reads airbase.json for project configuration
2. If no local image exists, automatically builds from Dockerfile
3. Sends deployment request to Airbase API
4. Airbase pulls container image from registry
5. Deploys container to Kubernetes cluster
6. Configures ingress (HTTPS endpoint)
7. Application becomes accessible

Deployment Time¶

Typical: 30 seconds - 2 minutes

Output¶

Project: my-app (runtime/demo)
Environment: staging
Image: local.airbase.sg/demo:abc123
Port ($PORT): 3000
Instance Type: nano

Deployed my-app in staging (runtime/demo:staging)
Visit https://staging--demo.app.tc1.airbase.sg
⠋ Pushing image...
⠙ Saving image...
⠸ Deploying container...
⠼ Waiting for deployment...
✓ Deployment successful

URL Patterns¶

Important: For production, omit the environment name (airbase deploy -y). Using "production" as an environment name will create https://production--project-name.app.tc1.airbase.sg instead of the clean production URL.

When to Use¶

Deploy only (configuration changes):

airbase deploy -y

Build + Deploy (code changes):

airbase build && airbase deploy -y

Environment Variables¶

CLI automatically reads and sends environment variables from:

• .env - For default/production environment
• .env.ENVIRONMENT - For named environments (e.g., .env.staging)

See Environment Variables Reference for details.

Confirmation Prompts¶

Default environment (production): - Prompt defaults to "N" (requires explicit confirmation) - Use --yes flag to skip prompt

Named environments: - Prompt defaults to "Y" (easier iteration) - Use --yes flag to skip prompt

Troubleshooting¶

Issue: Project handle not found

Error: Project not found

Solution: Verify handle in airbase.json matches your project in Airbase Console.

Issue: Port mismatch

Application doesn't respond after deployment.

Solution: Ensure port in airbase.json matches the port your application listens on.

Issue: Image not found

Error: Image not found in registry

Solution: Run airbase build first, or CLI will automatically build if no image exists.

Issue: Deployment timeout

Error: Deployment timed out

Solution: Check application logs in Airbase Console. Application may be crashing on startup.

airbase destroy¶

Remove a deployment from Airbase.

Usage¶

airbase destroy [OPTIONS] [ENVIRONMENT]

Legacy syntax (still valid):

airbase container destroy [OPTIONS] [ENVIRONMENT]

Description¶

Removes your application from the specified environment, freeing resources and making the URL inaccessible. This action is irreversible.

Arguments¶

Flags¶

Examples¶

Destroy default environment (production):

airbase destroy -y

Destroy named environment:

airbase destroy staging -y
airbase destroy development -y
airbase destroy feature-auth -y

Legacy syntax:

airbase container destroy -y
airbase container destroy staging -y

Destruction Process¶

1. CLI sends destroy request to Airbase API
2. Airbase removes Kubernetes deployment
3. Ingress (HTTPS endpoint) is removed
4. Resources are freed
5. URL becomes inaccessible

Propagation Time¶

Wait 30-60 seconds for changes to fully propagate across the infrastructure.

Output¶

Undeploying from staging environment...
✓ Undeployment successful
✓ Resources freed

Verification¶

After destruction, verify URL is inaccessible:

# Wait for propagation
sleep 60

# Check URL (should fail)
curl -I https://staging--myproject.app.tc1.airbase.sg

Expected: Connection error or 404 response.

Confirmation Prompts¶

Default environment (production): - Prompt defaults to "N" (protection against accidental deletion) - Use --yes flag to skip prompt

Named environments: - Prompt defaults to "Y" (easier cleanup) - Use --yes flag to skip prompt

Important Notes¶

• Irreversible: Deployment cannot be recovered
• No data loss: Container images remain in registry
• Redeployable: Can redeploy anytime with airbase deploy
• Environment-specific: Only removes from specified environment
• Be careful: airbase destroy -y destroys production!

Troubleshooting¶

Issue: Environment not found

Error: Deployment not found

Solution: Verify environment name and that application is deployed there.

Issue: URL still accessible after destroy

Solution: Wait 30-60 seconds for propagation. If still accessible after 2 minutes, check Airbase Console.

airbase version¶

Display version information for the Airbase CLI.

Usage¶

airbase version
airbase -v

Flags¶

Output Format¶

Version: v1.0.3
Commit: 0c3a3f4
Build Time: 2026-03-30T14:19:11Z

Examples¶

# Display version
airbase version

# Short form
airbase -v

Commands That DO NOT Exist¶

These commands are INVALID and will fail. Do not attempt to use them.

Notes¶

• Logs: Access logs through the Airbase Console web interface
• Status: Check if your application is running by visiting the deployment URL
• Authentication: No identity verification command; re-run airbase login if auth fails
• Rollback: Deploy a previous version by checking out old code and running airbase build && airbase deploy -y
• Restart: Redeploy to restart: airbase deploy -y
• Scaling: Change instanceType in airbase.json and redeploy
• Project Linking: Use airbase configure to set up project configuration

Common Command Patterns¶

Initial Setup¶

# Step 1: Authenticate
airbase login

# Step 2: Configure project
airbase configure

# Step 3: Build and deploy
airbase build && airbase deploy -y

Build & Deploy (Code Changes)¶

# When you've changed application code or dependencies
airbase build && airbase deploy -y                    # Default environment (production)
airbase build && airbase deploy staging -y            # Staging

Deploy Only (Configuration Changes)¶

# When you've only changed airbase.json or .env files
airbase deploy -y                                     # Default environment (production)
airbase deploy staging -y                             # Staging

Update Existing Deployment¶

# Code changes: rebuild and redeploy to production
airbase build && airbase deploy -y

# Config changes only: just redeploy to production
airbase deploy -y

Staging to Production Workflow¶

# Step 1: Test in staging with code changes
airbase build && airbase deploy staging -y

# Step 2: Verify staging works
curl https://staging--my-project.app.tc1.airbase.sg

# Step 3: Promote same image to production (no environment name)
airbase deploy -y

# Step 4: Verify production
curl https://my-project.app.tc1.airbase.sg

Multi-Environment Deployment¶

# Build once
airbase build

# Deploy to all environments
airbase deploy development -y
airbase deploy staging -y
airbase deploy -y  # production

Clean Up¶

# Remove staging environment
airbase destroy staging -y

# Remove development environment
airbase destroy development -y

# Remove default environment (production) - BE CAREFUL!
airbase destroy -y

Important: Always omit environment name for production. Using production as an environment name will create https://production--project-name.app.tc1.airbase.sg instead of the clean production URL.

CI/CD Usage¶

CLI is designed for automation in CI/CD pipelines.

Using CI Mode¶

For automated deployments, use the --ci global flag for optimized CI/CD behavior:

# Deploy without prompts (use --ci flag for CI mode)
airbase deploy -y --ci

# Or with specific image
airbase build --ci
airbase deploy --image my-app:$CI_COMMIT_SHA -y --ci

GitHub Actions Example¶

name: Deploy to Airbase

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Airbase CLI
        run: curl -fsSL https://console.airbase.tech.gov.sg/dist/install.sh | sh

      - name: Authenticate
        run: airbase login
        env:
          AIRBASE_TOKEN: ${{ secrets.AIRBASE_TOKEN }}

      - name: Build
        run: airbase build --ci

      - name: Deploy
        run: airbase deploy -y --ci

Authentication in CI/CD¶

For automated/CI/CD environments:

• Consult official documentation at https://go.gov.sg/airbase-docs
• Use service accounts or tokens (configuration varies by setup)
• Use --ci flag to optimize behavior for automation

Best Practices¶

• Always use --yes flag to skip prompts
• Use --ci flag for CI-optimized behavior
• Use --output json for parsing deployment information
• Store deployment URLs with -o flag for downstream jobs
• Use environment variables for sensitive data

Configuration Files¶

airbase.json¶

CLI reads configuration from airbase.json in the current directory.

Required fields: - framework: Must be "container" - handle: Project identifier (format: team-name/project-name) - port: Application listening port

Optional fields: - instanceType: Instance size (default: "nano")

Example:

{
  "framework": "container",
  "handle": "runtime/demo",
  "port": 3000,
  "instanceType": "nano"
}

See airbase.json Reference for complete specification.

Environment Variables Files¶

CLI reads environment variables from .env files:

• .env - Default/production environment
• .env.staging - Staging environment
• .env.development - Development environment
• .env.ENVIRONMENT - Custom environment

See Environment Variables Reference for details.

Error Messages¶

Authentication Errors¶

Error: Not authenticated. Run 'airbase login' first.

Solution: Run airbase login to authenticate.

Configuration Errors¶

Error: airbase.json not found

Solution: Create airbase.json or run airbase configure.

Error: Invalid project handle format

Solution: Handle must be in format team-name/project-name.

Build Errors¶

Error: Docker not running

Solution: Start Docker Desktop or Docker service.

Error: Dockerfile not found

Solution: Ensure Dockerfile exists or use --file flag.

Deployment Errors¶

Error: Project not found

Solution: Verify project handle in Airbase Console.

Error: Port must be between 1 and 65535

Solution: Use valid port number in airbase.json.

Error: Image not found in registry

Solution: Run airbase build first.

Network Errors¶

Error: Failed to connect to Airbase API

Solution: Check network connectivity, verify access to console.airbase.tech.gov.sg.

Error: Request timeout

Solution: Retry command. If persists, check Airbase status.

Platform-Specific Notes¶

macOS¶

• Credentials stored in: ~/Library/Application Support/airbase/
• Docker typically via Docker Desktop
• Browser: Opens default browser for authentication

Linux¶

• Credentials stored in: ~/.config/airbase/
• Docker via Docker Engine or Docker Desktop
• Browser: Uses xdg-open to launch browser

Windows¶

• Credentials stored in: %APPDATA%\airbase\
• Docker typically via Docker Desktop
• Browser: Opens default browser for authentication

Version History¶

v1.0.3 (Current)¶

• Binary distribution via shell script installer
• Modern command syntax: airbase [command]
• Legacy syntax support: airbase container [command]
• Global flags: --ci, --verbose, --output, etc.
• Commands: login, configure, build, deploy, destroy, version
• Project commands: list, get
• Environment support
• Environment variables support

See Also¶

• How-To: Build and Deploy Applications
• How-To: Manage Environments
• Reference: Dockerfile Requirements
• Reference: airbase.json Configuration
• Reference: Environment Variables
• Tutorial: Getting Started