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¶

Current CLI (npm-based)¶

npm install -g @airbase/airbase-cli@containers

Version: 3.0.0-beta.15 or later

Global Options¶

These options are available for all commands:

Commands Overview¶

airbase login¶

Authenticate with Airbase to access deployment functionality.

Usage¶

airbase login

Description¶

Opens your default browser to authenticate with Airbase. After successful authentication, stores credentials locally for subsequent commands.

Authentication Flow¶

1. CLI opens browser to Airbase Console
2. User logs in with government credentials
3. Browser redirects back with authentication token
4. CLI stores token locally
5. Authentication complete

Authentication Storage¶

Credentials are stored in: - Location: ~/.airbase/credentials (or platform-specific config directory) - Format: Encrypted token file - Scope: Per-user, system-wide

Examples¶

# Interactive login
airbase login

Expected output:

Opening browser for authentication...
✓ Authentication successful
✓ Credentials saved

Troubleshooting¶

Issue: Browser doesn't open

Try manually navigating to the authentication 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

Issue: Already authenticated

Re-running airbase login will re-authenticate and overwrite existing credentials.

Exit Codes¶

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.

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
airbase configure

Expected interaction:

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

Notes¶

• Must be authenticated (airbase login) before running
• Overwrites existing airbase.json if present
• Creates file in current working directory

Exit Codes¶

airbase project¶

Manage Airbase projects and project linking.

airbase project link¶

⚠️ DEPRECATED - DO NOT USE

This command is deprecated and can cause deployment issues.

Use airbase configure instead - It's the recommended way to set up your project for deployment.

# ✅ Recommended - Use airbase configure
airbase configure

# Then deploy with explicit project (configured in airbase.json)
airbase container deploy --yes staging

# ❌ Deprecated - Do not use project link
airbase project link team/project

Why use airbase configure instead: - Sets up airbase.json with correct project handle - Configuration is committed to repository (team-wide) - Explicit and transparent - no hidden link files - Works seamlessly in CI/CD pipelines - Prevents deployment to wrong project

Issues with airbase project link: - Creates hidden .airbase/ directory with link file - Can cause confusion about which project is being deployed - Link file conflicts in team environments - Not portable across team members - Makes deployments implicit and harder to debug

See: airbase configure for the recommended setup workflow.

airbase project list¶

Display all projects accessible from your Airbase account.

Usage:

airbase project list

Description:

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

Sample output:

$ airbase project list
agency-test
simple-next-app
template-nextjs-helloworld

Use cases: - Find project handles before running airbase configure - Verify access to projects - Discover available projects in your account

airbase container build¶

Build a container image from your Dockerfile.

Usage¶

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
• Docker Buildx plugin must be installed (see below)
• Dockerfile must exist in current directory
• Must be authenticated (airbase login)
• Dockerfile must follow Airbase platform constraints (non-root user, proper ownership)

Installing Docker Buildx:

Docker Buildx is not installed by default on SEED devices or after initial Docker setup.

1. Check if Buildx is available:

   docker buildx version
   

2. If not installed, install it:

   mkdir -p ~/.docker/cli-plugins
   curl -SL https://github.com/docker/buildx/releases/latest/download/docker-buildx-$(uname -s)-$(uname -m) -o ~/.docker/cli-plugins/docker-buildx
   chmod +x ~/.docker/cli-plugins/docker-buildx
   

3. Verify installation:

   docker buildx version
   # Should show: github.com/docker/buildx v0.x.x
   

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 via API
5. Image ready for deployment

Options¶

Examples¶

# Build with default Dockerfile
airbase container build

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

# Build for specific platform
airbase container build --platform linux/arm64

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)

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.

Exit Codes¶

airbase container deploy¶

Deploy your application to Airbase.

Usage¶

airbase container deploy [OPTIONS] [ENVIRONMENT]

Description¶

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

Arguments¶

Options¶

Examples¶

Deploy to default environment (production):

airbase container deploy --yes

Deploy to named environment:

airbase container deploy --yes staging
airbase container deploy --yes development
airbase container deploy --yes feature-auth

Deploy with custom settings:

# Deploy specific image
airbase container deploy --yes --image myapp:v1.2.3

# Override port
airbase container deploy --yes --port 8080

# Override instance type
airbase container deploy --yes --instance-type b.small

# Write URL to file
airbase container deploy --yes --output deployment-url.txt

Redeploy without rebuilding:

# Uses last built image
airbase container deploy --yes

Deployment Process¶

1. CLI reads airbase.json for project configuration
2. Sends deployment request to Airbase API
3. Airbase pulls container image from registry
4. Deploys container to Kubernetes cluster
5. Configures ingress (HTTPS endpoint)
6. 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...

URL Patterns¶

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 container build first.

Issue: Deployment timeout

Error: Deployment timed out

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

Exit Codes¶

airbase container destroy¶

Remove a deployment from Airbase.

Usage¶

airbase container destroy [OPTIONS] [ENVIRONMENT]

Description¶

Removes your application from the specified environment, freeing resources and making the URL inaccessible.

Arguments¶

Options¶

Examples¶

Undeploy from default environment:

airbase container destroy --yes

Undeploy from named environment:

airbase container destroy --yes staging
airbase container destroy --yes development
airbase container destroy --yes feature-auth

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 undeployment, 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¶

• Destructive operation: Cannot be undone
• No data loss: Container images remain in registry
• Redeployable: Can redeploy anytime with airbase container deploy
• Environment-specific: Only removes from specified environment

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.

Exit Codes¶

Common Command Patterns¶

First-Time Deployment Workflow¶

# Step 1: Authenticate
airbase login

# Step 2: Configure project
airbase configure

# Step 3: Build container
airbase container build

# Step 4: Deploy to production
airbase container deploy --yes

Development Workflow¶

# Make code changes...

# Rebuild
airbase container build

# Deploy to staging
airbase container deploy --yes staging

# Test at staging URL...

# If good, deploy to production
airbase container deploy --yes

Multi-Environment Deployment¶

# Build once
airbase container build

# Deploy to all environments
airbase container deploy --yes development
airbase container deploy --yes staging
airbase container deploy --yes production

Cleanup Workflow¶

# Remove feature environment
airbase container destroy --yes feature-auth

# Remove staging
airbase container destroy --yes staging

Exit Codes Summary¶

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")

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 complete specification.

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 container 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.

Environment Variables (CLI Behavior)¶

CLI behavior can be modified with environment variables:

Examples¶

# Use custom config path
export AIRBASE_CONFIG_PATH=/path/to/config
airbase login

# Connect to remote Docker daemon
export DOCKER_HOST=tcp://remote-host:2375
airbase container build

# Disable colors (CI/CD)
export NO_COLOR=1
airbase container deploy --yes

CI/CD Usage¶

CLI is designed for automation in CI/CD pipelines.

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: npm install -g @airbase/airbase-cli@containers

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

      - name: Build
        run: airbase container build

      - name: Deploy
        run: airbase container deploy --yes

Authentication in CI/CD¶

Use AIRBASE_TOKEN environment variable to authenticate non-interactively:

export AIRBASE_TOKEN="your-token-here"
airbase login  # Authenticates using token instead of browser

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¶

Current: 3.0.0-beta.15¶

• Initial container deployment support
• Commands: login, configure, build, deploy, destroy
• 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