Skip to content

Upgrade to New CLI

Upgrade from the npm-based CLI to the new golang binary

The Airbase CLI has been updated with a new binary that provides improved performance and simpler installation. This guide will help you migrate from the old npm-based CLI to the new binary.

Why Upgrade?

The old npm CLI (@airbase/airbase-cli@containers) is deprecated. The backend API has been upgraded to a new architecture that only works with the new golang CLI.

Benefits of the new CLI: - ✅ Faster performance - ✅ Simpler installation (no Node.js required) - ✅ Smaller download size - ✅ Shorter command syntax (airbase build instead of airbase container build) - ✅ Auto build-and-deploy feature

Quick Check: Do You Need to Upgrade?

Run this command to check your current CLI version:

airbase -v

If you see this - you need to migrate: 

3.0.0-beta.15

If you see this - you're already using the new CLI: 

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

Upgrade Steps

Step 1: Uninstall Old CLI

Remove the old npm-based CLI:

sudo npm uninstall --global @airbase/airbase-cli

Verify removal: 

airbase -v

You should see "command not found" or nothing.

Still See Old Version?

If airbase -v still shows 3.0.0-beta.15, the CLI may be installed via a package manager (mise, homebrew, etc.). See Troubleshooting Multiple Installations.

Step 2: Remove Old Authentication File

Remove the old authentication file:

rm ~/.airbaserc

Verify removal: 

cat ~/.airbaserc

Should show "No such file or directory".

Step 3: Install New CLI

Visit the CLI download page: 

https://go.gov.sg/airbase-cli

The page will detect your system architecture and provide the appropriate installation command.

Example installation command: 

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

Installation Location

The installer will place the binary in one of two locations:

  • ~/.local/bin/airbase (if ~/.local/bin exists)
  • /usr/local/bin/airbase (if ~/.local/bin doesn't exist)

Step 4: Verify Installation

Check the new CLI version:

airbase -v

Expected output: 

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

Verify binary location: 

which airbase

Expected output (if installed to ~/.local/bin): 

/Users/username/.local/bin/airbase

Or (if installed to /usr/local/bin): 

/usr/local/bin/airbase

Step 5: Authenticate

Authenticate with the new CLI:

airbase login

Authentication flow:

  1. CLI generates a one-time verification code
  2. Open the provided URL in your browser
  3. Verify the code matches on both CLI and browser
  4. Click "Continue" and "Accept" to authorize
  5. Name your API token (e.g., "my-laptop")
  6. CLI receives confirmation

Terminal view:

You'll see a verification code like this: 

Verification code: ABCD-1234
Please visit: https://console.airbase.tech.gov.sg/auth/...

Browser view:

The browser will show the same code and ask you to confirm.

Authentication Complete

Your credentials are saved in ~/.airbaserc in the new format.

Step 6: Verify Authentication

Check that authentication worked:

cat ~/.airbaserc

Expected format (new CLI): 

ACCESS_TOKEN=eyJhbGci...
AIRBASE_ENDPOINT=https://console.airbase.tech.gov.sg
EXPIRY=2026-03-06T10:53:31+08:00
REFRESH_TOKEN=eyJhbGci...

Step 7: Test Deployment

Before testing, ensure: - You have created a team in Airbase Console - You have created a project within that team - Note down your project handle (format: team-name/project-name)

Navigate to your project directory: 

cd /path/to/your-project

Configure your project: 

airbase configure

This command will: - Show a list of your projects - Create an airbase.json file linking your code to the project

Build and deploy: 

# Build container image
airbase build

# Deploy to staging
airbase deploy --yes staging

New Command Syntax

The new CLI supports shorter commands: - airbase build (instead of airbase container build) - airbase deploy (instead of airbase container deploy)

Old commands still work for backwards compatibility.

Command Differences

Old CLI vs New CLI

Task Old Command New Command
Build airbase container build airbase build
Deploy airbase container deploy --yes airbase deploy --yes
Deploy to env airbase container deploy --yes staging airbase deploy --yes staging
Destroy airbase container destroy --yes airbase destroy --yes
Configure airbase configure airbase configure (same)
Login airbase login airbase login (same)

Note: Old commands still work with the new CLI for backwards compatibility.

New Features

1. Auto Build-and-Deploy

The new CLI can automatically build before deploying:

# This will build AND deploy in one command
airbase deploy --yes staging

To skip building and deploy a specific image: 

airbase deploy --image my-image:v1.0 --yes

2. Shorter Commands

# New syntax (recommended)
airbase build
airbase deploy --yes

# Old syntax (still works)
airbase container build
airbase container deploy --yes

Troubleshooting

Issue: Old CLI Still Present After Uninstall

Symptom: 

$ airbase -v
3.0.0-beta.15

Cause: CLI installed via package manager (mise, homebrew, asdf, etc.) that takes PATH precedence.

Solution:

Find where the old CLI is located: 

which airbase

If it shows a path like: 

airbase is /Users/username/.local/share/mise/.../airbase

Remove it: 

# For mise users
mise uninstall node  # Adjust version as needed

# For homebrew users
brew uninstall airbase-cli

# Or manually remove
sudo rm $(which airbase)

Verify removal: 

which airbase
# Should show "not found" or the new CLI location (/Users/username/.local/bin/airbase or /usr/local/bin/airbase)

Issue: Command Not Found After Installation

Symptom: 

$ airbase -v
-bash: airbase: command not found

Cause: - Installation directory (~/.local/bin or /usr/local/bin) not in PATH - Installation failed

Solution:

Check if binary exists: 

ls -la ~/.local/bin/airbase
# Or check
ls -la /usr/local/bin/airbase

If binary exists in ~/.local/bin:

Add ~/.local/bin to PATH: 

# For bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

If binary exists in /usr/local/bin:

Add /usr/local/bin to PATH: 

# For bash
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

If binary doesn't exist:

Re-run installation from https://go.gov.sg/airbase-cli

Issue: Authentication Fails

Symptom: - Browser flow doesn't complete - "Invalid credentials" errors

Solution:

  1. Check verification codes match:
  2. Code in terminal should match code in browser

  3. If they don't match, restart authentication

  4. Clear and re-authenticate: 

    rm ~/.airbaserc
airbase login

  5. Check internet connectivity: 

    ping console.airbase.tech.gov.sg

  6. Ensure you're logged into Airbase Console:

  7. Visit https://go.gov.sg/airbase
  8. Login with TechPass or gov.sg email

Issue: Massive tRPC Error

Symptom: 

TRPCClientError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON
    at TRPCClientError.from (file:///.../TRPCClientError-0de4d231.mjs:37:16)
    ...
    status: 404,
    statusText: 'Not Found',

Cause: Using old npm CLI after backend API has migrated.

Solution: You must migrate to the new CLI immediately. The old CLI is no longer functional. Follow all steps in this guide starting from Step 1.

Issue: Wrong Architecture on macOS

Symptom: 

Bad CPU type in executable

Cause: Running wrong binary for your Mac's architecture.

Solution:

Check your Mac architecture: 

uname -m
# arm64 = Apple Silicon (M1/M2/M3)
# x86_64 = Intel

Download the correct binary from https://go.gov.sg/airbase-cli

Issue: macOS Gatekeeper Blocking Binary

Only for Manual Downloads

This issue only occurs if you manually downloaded the CLI binary. The install script (recommended method) does not require these steps. Use the install script from https://go.gov.sg/airbase-cli to avoid this issue.

Symptom: 

"airbase" cannot be opened because the developer cannot be verified

Solution:

Remove quarantine attribute (use the path where your binary is installed): 

# If installed to ~/.local/bin
sudo xattr -rd com.apple.quarantine ~/.local/bin/airbase

# If installed to /usr/local/bin
sudo xattr -rd com.apple.quarantine /usr/local/bin/airbase

Or allow in System Preferences: - System Preferences → Security & Privacy → General → "Allow"

Verification Checklist

After completing all migration steps, verify your setup:

  • Check CLI version: airbase -v shows version with commit hash
  • Check binary location: which airbase shows /Users/username/.local/bin/airbase or /usr/local/bin/airbase
  • Check authentication: cat ~/.airbaserc shows new format (ACCESS_TOKEN, REFRESH_TOKEN)
  • Test configuration: airbase configure lists your projects
  • Test Docker: docker ps works without error
  • Test build: airbase build completes successfully
  • Test deploy: airbase deploy --yes staging works

Getting Help

Additional Resources

When to Contact Support

Contact support if you experience: - SEED laptop certificate issues - Persistent authentication failures after troubleshooting - Installation issues on corporate/restricted machines - Unexpected CLI behavior

What to provide: 

# CLI version
airbase -v

# Operating system
uname -a  # macOS/Linux

# Architecture
uname -m

# Binary location
which airbase

# Authentication format (redact tokens)
cat ~/.airbaserc | sed 's/=.*/=REDACTED/g'

# Full error message

Summary

Key migration steps:

  1. ✅ Uninstall old npm CLI: sudo npm uninstall --global @airbase/airbase-cli
  2. ✅ Remove old auth file: rm ~/.airbaserc
  3. ✅ Install new CLI from https://go.gov.sg/airbase-cli
  4. ✅ Verify installation: airbase -v shows detailed version
  5. ✅ Authenticate: airbase login
  6. ✅ Test deployment: airbase configure, airbase build, airbase deploy

The new CLI offers: - Faster performance - Simpler installation - Shorter commands - Auto build-and-deploy

You're now ready to use the new Airbase CLI!

See Also