ff-cli

Standalone command-line tool for building, deploying, and operating FireFoundry agent bundles. Ships as a single binary with native Kubernetes and container integration — no runtime dependencies.

Why ff-cli

ff-cli is your primary interface for the FireFoundry platform. It ships as a single binary with zero dependencies. Unlike tools that require separate installations of kubectl, helm, or docker, ff-cli integrates Kubernetes, Helm, and container operations natively — giving you streamlined operations with proper error handling and richer output.

637+ unit tests ensure reliability across all packages. The clean three-layer architecture — CLI commands, business logic managers, and core executors — keeps the codebase maintainable while supporting the full lifecycle from scaffolding to production operations.

Cloud provider operations use native Azure, AWS, and GCP integration for resource provisioning, identity management, and cluster creation — no separate cloud CLI tools required.

Key Capabilities

• Zero Dependencies: Single binary — no separate kubectl, helm, or container CLI required
• Kubernetes-Native: Native Kubernetes integration for pod management, log streaming, scaling, and health checks
• Helm Integration: Full chart operations — install, upgrade, rollback, template, and chart management
• Container Operations: Build, tag, and push container images natively
• Multi-Cloud: Native Azure, AWS, and GCP integration for cloud resource management
• Agent Bundle Lifecycle: Create, build, deploy, and monitor agent bundles from a single tool
• Cluster Management: Initialize, configure, and destroy Kubernetes clusters
• Environment Promotion: Promote agent bundles through dev, staging, and production with gates
• Operations Dashboard: Real-time status, log streaming, pod restarts, and scaling from the terminal
• Dual Build Modes: Same codebase produces ff-cli (developer-facing) and ff-admin (admin operations via build tag)

Command Groups

Commands are organized into logical groups covering the full platform lifecycle — from creating an application to deploying agent bundles to managing day-2 operations.

Each group maps to a manager in the internal layer that handles orchestration, validation, and error reporting. Run ff-cli <group> --help to see all available subcommands and flags.

Agent Bundle Workflow

Scaffold a new agent bundle, build it into a container image, deploy to an environment, and monitor it — all from a single tool.

The agent-bundle create command generates the project structure, Dockerfile, Helm chart, and configuration files from embedded templates. Building and deploying use native container and Helm integration — no external tools required.

# Create a new agent bundle project
ff-cli agent-bundle create my-assistant --template hello-world
cd my-assistant

# Build the container image
ff-cli agent-bundle build

# Deploy to development
ff-cli agent-bundle deploy --env dev

# Stream logs
ff-cli ops logs --env dev --follow

# Check status
ff-cli ops status --env dev

Cluster & Environment Management

Stand up infrastructure, create isolated environments, and promote agent bundles through your deployment pipeline.

Cluster initialization provisions the Kubernetes cluster through the appropriate cloud provider SDK, configures networking, and installs the FireFoundry platform components via Helm. Environments are isolated namespaces with their own secrets, configurations, and resource quotas.

# Initialize a new cluster
ff-cli cluster init --provider azure --region westus2

# Create environments
ff-cli environment create dev
ff-cli environment create staging
ff-cli environment create prod

# Promote through environments
ff-cli agent-bundle deploy --env dev
# ... test, validate ...
ff-cli agent-bundle deploy --env staging
# ... test, validate ...
ff-cli agent-bundle deploy --env prod

ff-admin

Same codebase, different build tag. ff-admin exposes additional administrative commands for platform operators: service management, access control, audit logging, and cluster-level configuration. Built with a single flag:

# Build the admin binary
go build -tags admin -o ff-admin ./cmd/ff-cli

# Admin-only commands
ff-admin access-control list
ff-admin audit logs --since 24h
ff-admin deploy service broker --env prod
ff-admin cluster edit --scale-pool system=3

Admin commands are compiled out of the standard ff-cli binary entirely. Go build tags ensure the admin surface area — access control, audit, deployment management, and cluster editing — never ships to developers. One repo, two binaries, zero duplication.

Use Cases