Installation

Installation

This guide covers installing the FlightStack CLI and setting up build agents on different platforms.

CLI Installation

The FlightStack CLI is the primary tool for managing your build agents and interacting with FlightStack from the command line.

macOS

Homebrew (Recommended)

# Add the FlightStack tap
brew tap voostack/tap

# Install FlightStack
brew install flightstack

# Verify installation
flightstack --version

Direct Download

# Download the latest release
curl -fsSL https://get.flightstack.dev | bash

# Or download manually from GitHub releases
# https://github.com/voostack/flightstack/releases

# Move to PATH (if needed)
sudo mv flightstack /usr/local/bin/

# Verify installation
flightstack --version

Build from Source

# Clone the repository
git clone https://github.com/voostack/flightstack.git
cd flightstack

# Build the CLI
melos build:cli

# The binary is at packages/flightstack_cli/build/

Linux

Install Script

# Download and install
curl -fsSL https://get.flightstack.dev | bash

# Verify installation
flightstack --version

Manual Download

# Download the latest release
wget https://github.com/voostack/flightstack/releases/latest/download/flightstack-linux-x64.tar.gz

# Extract
tar -xzf flightstack-linux-x64.tar.gz

# Move to PATH
sudo mv flightstack /usr/local/bin/

# Make executable
chmod +x /usr/local/bin/flightstack

# Verify installation
flightstack --version

Windows

Scoop

# Add the FlightStack bucket
scoop bucket add voostack https://github.com/voostack/scoop-bucket

# Install FlightStack
scoop install flightstack

# Verify installation
flightstack --version

Manual Download

1. Download flightstack-windows-x64.zip from GitHub Releases
2. Extract to a folder (e.g., C:\Program Files\FlightStack)
3. Add the folder to your PATH environment variable
4. Open a new terminal and verify: flightstack --version

Build Agent Requirements

Build agents are the machines that execute your builds. Here are the requirements for each platform:

macOS Agent (for iOS builds)

Requirement	Minimum	Recommended
macOS	12.0 (Monterey)	14.0+ (Sonoma)
Xcode	14.0	15.0+
RAM	8 GB	16 GB+
Storage	50 GB free	100 GB+ free

Required software:

# Install Xcode from the App Store, then:
sudo xcode-select --install
sudo xcodebuild -license accept

# Install Flutter
brew install flutter
flutter doctor

# Install CocoaPods (for iOS dependencies)
sudo gem install cocoapods

Linux Agent (for Android/Web builds)

Requirement	Minimum	Recommended
Ubuntu	20.04 LTS	22.04 LTS
RAM	4 GB	8 GB+
Storage	30 GB free	50 GB+ free

Required software:

# Update system
sudo apt update && sudo apt upgrade -y

# Install dependencies
sudo apt install -y git curl unzip

# Install Flutter
sudo snap install flutter --classic
flutter doctor

# Install Android SDK (for Android builds)
sudo apt install -y android-sdk
flutter config --android-sdk /usr/lib/android-sdk

Windows Agent

Requirement	Minimum	Recommended
Windows	10 (1903+)	11
RAM	4 GB	8 GB+
Storage	30 GB free	50 GB+ free

Required software:

# Install Flutter (using Chocolatey)
choco install flutter

# Or download from flutter.dev
# https://docs.flutter.dev/get-started/install/windows

# Install Android Studio for Android SDK
choco install androidstudio

# Verify
flutter doctor

Post-Installation Setup

1. Verify Installation

   # Check CLI version
   flightstack --version
   
   # Check available commands
   flightstack --help

2. Authenticate

   flightstack login

   This opens your browser for authentication. After logging in, you’ll see confirmation in the terminal.

3. Register Your Agent

   flightstack agent register

   The CLI will detect your system capabilities automatically.

4. Configure Auto-Start (Optional)

   To have the agent start automatically on boot:

   flightstack agent install

   See Auto-Start on Boot for platform-specific details.

Updating

CLI Updates

Homebrew

brew update && brew upgrade flightstack

Scoop

scoop update flightstack

Manual

Download the latest release from GitHub and replace the existing binary.

Agent Updates

The agent checks for updates automatically. To manually update:

# Stop the running agent
flightstack agent stop

# Update the CLI (includes agent)
# Use your package manager or re-download

# Start the agent again
flightstack agent start

Uninstalling

Remove CLI

Homebrew

brew uninstall flightstack

Manual

sudo rm /usr/local/bin/flightstack
rm -rf ~/.flightstack

Remove Startup Service

flightstack agent uninstall

This removes the startup configuration but keeps your agent registered.

Completely Unregister Agent

# Stop and uninstall
flightstack agent stop
flightstack agent uninstall

# Delete the agent from FlightStack
flightstack agent delete <agent-id>

# Remove local configuration
rm -rf ~/.flightstack

Troubleshooting Installation

Common Issues

If you encounter permission errors, don’t use sudo with brew or scoop. Check that your PATH is configured correctly.

”command not found”

The binary isn’t in your PATH. Either:

• Add the installation directory to your PATH
• Move the binary to a directory in your PATH (e.g., /usr/local/bin)

“Permission denied”

# Make the binary executable
chmod +x /path/to/flightstack

Flutter not detected

Ensure Flutter is installed and in your PATH:

# Check Flutter installation
which flutter
flutter doctor

# If not found, add to PATH
export PATH="$PATH:/path/to/flutter/bin"

Xcode issues (macOS)

# Accept Xcode license
sudo xcodebuild -license accept

# Set Xcode path
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

# Install command line tools
xcode-select --install

Need more help? Check our Troubleshooting Guide or join our Discord.