Apito CLI

🚀 Apito CLI is a powerful command-line tool for managing projects, plugins, functions, and deployments on the Apito platform. It provides a seamless development experience from local development to cloud deployment with enhanced database management, plugin hot-reload system, and Docker integration.

🆕 What's New in Latest Version

🔄 Automatic Version Management

• Smart Version Tracking: Automatically fetches and stores latest engine and console versions
• Update Detection: Checks for new versions every time you run apito start
• Interactive Updates: Choose which components to update with a simple prompt
• Version Pinning: Uses specific version tags instead of :latest for consistent deployments
• Zero-Downtime Updates: Pull new images and regenerate docker-compose.yml seamlessly
• GitHub Integration: Fetches versions directly from GitHub releases and container registry

🔌 Plugin Management System

• Hot Reload Plugins: Deploy and update HashiCorp plugins without server restarts
• Multi-language Support: Create plugins in Go, JavaScript, or Python
• Secure Deployment: Cloud sync key authentication for plugin operations
• Plugin Lifecycle Management: Create, deploy, update, start, stop, restart, and delete plugins
• Template Scaffolding: Generate plugin scaffolds with best practices built-in
• Real-time Status Monitoring: Live plugin status and health checks

✨ Enhanced Database Management

• Interactive Database Setup: Choose between default credentials or custom configuration
• Multiple Database Support: PostgreSQL, MySQL, MariaDB, MongoDB, Redis, SQL Server
• Persistent Data Volumes: Named Docker volumes for data persistence
• Configuration Overwrite Protection: Confirmation prompts before overwriting existing settings

🐳 Improved Docker Integration

• Comprehensive Docker Checks: Installation, Docker Compose, and daemon status verification
• Consistent Container Naming: apito-system-{engine} and apito-project-{engine} patterns
• Volume Management: Automatic volume creation with matching container names
• OS-Specific Guidance: Helpful instructions for Docker installation across platforms

⚙️ Enhanced Configuration System

• Centralized .env Management: New env.go with comprehensive environment variable operations
• Configuration Persistence: Database settings saved to ~/.apito/bin/.env
• Smart Configuration Loading: Automatic detection of system vs. project database settings
• Backup and Validation: Environment file backup and required variable validation

🔧 CLI Command Enhancements

• Database-Specific Commands: --db system and --db project flags for granular control
• Separated Concerns: Database setup moved from init to dedicated start --db commands
• Consistent Command Patterns: Unified --db flag across start, stop, and restart commands
• Enhanced Status Monitoring: Database status display in apito status command
• Comprehensive Logging: New apito logs command for service and database logs

📦 Installation

Homebrew (macOS and Linux)

brew tap apito-io/tap
brew install apito-cli

Quick Install (Linux & macOS)

curl -fsSL https://get.apito.io/install.sh | bash

Manual Install

# Download the installer
wget -O install.sh https://get.apito.io/install.sh

# Make it executable
chmod +x install.sh

# Run the installer
./install.sh

Verify Installation

apito --version

🎯 Getting Started

0. Initialize Apito CLI (First Time Setup)

apito init

This command will:

• Create core directories under ~/.apito (e.g., bin/, db/, logs/, run/)
• Create ~/.apito/bin/.env with default system configuration
• Ask you to choose a run mode: Docker (recommended, default) or Manual, and save it to ~/.apito/config.yml
• Database setup is now handled separately - use apito start --db system or apito start --db project
• Validate database and environment settings
• Check port availability (5050, 4000) and optionally free them (Manual mode only)
• Guide you through any missing configuration

1. Create Your First Project

apito create project -n my-awesome-app

This interactive command will:

• Create a new project directory
• Set up system and project databases
• Download the latest Apito engine
• Configure your project settings

2. Start Apito Engine and Console

apito start [--db system|project]

This command will (based on run mode stored in ~/.apito/config.yml):

• Docker mode (default, recommended):
  • Ensure ~/.apito/docker-compose.yml exists (engine + console)
  • Mount ~/.apito/db -> /app/db and ~/.apito/bin/.env -> /app/.env
  • Start services via docker compose -f ~/.apito/docker-compose.yml up -d
  • Optional: --db system or --db project to start specific database types
• Manual mode:
  • Download the latest Apito engine to ~/.apito/bin/engine
  • Download the latest console to ~/.apito/console
  • Install and configure Caddy to ~/.apito/bin/caddy
  • Check and free ports 5050/4000 if needed
  • Start engine and serve console locally (managed by PID + logs)

📚 Command Reference

For detailed command documentation, see:

• System Management - init, status, logs
• Database Management - start --db, stop --db, restart --db
• Plugin Management - config, account, plugin
• Monitoring & Observability - Status monitoring and logging
• Project Management - create command
• Development & Execution - start, stop, restart
• Building & Packaging - build command
• Updates & Maintenance - update command

🗂️ Project Structure

Apito CLI sets up the following structure:

~/.apito/
├── bin/
│   ├── engine               # Engine binary (Manual mode)
│   ├── caddy                # Caddy binary (Manual mode)
│   └── .env                 # System configuration mounted into engine container
├── db/                      # Persistent engine data volume (Docker mode)
├── docker-compose.yml       # Engine + Console compose (Docker mode)
├── db-compose.yml           # Database compose (generated when --db flag used)
├── console/                 # Console static files (Manual mode)
├── Caddyfile                # Console server config (Manual mode)
├── logs/                    # Service log files (Manual mode)
│   ├── engine.log          # Engine service logs
│   └── console.log         # Console service logs
├── run/                     # Process PID files (Manual mode)
│   ├── engine.pid
│   └── console.pid
└── config.yml               # CLI config (mode, plugin server URL, cloud sync key)

⚙️ Configuration

CLI Configuration (~/.apito/config.yml)

• mode - CLI run mode (docker or manual)
• default_account - Default account for plugin operations
• timeout - Request timeout in seconds (default: 30)
• default_plugin - Default plugin for operations
• engine_version - Current engine Docker image version (auto-managed)
• console_version - Current console Docker image version (auto-managed)
• accounts - Account configurations map (supports multiple accounts)

Engine Configuration (~/.apito/bin/.env)

The CLI manages engine configuration in ~/.apito/bin/.env:

System Configuration:

• ENVIRONMENT - local/development/staging/production
• COOKIE_DOMAIN - e.g., localhost
• CORS_ORIGIN - e.g., http://localhost:4000
• BRANKA_KEY - Generated secret key
• APITO_SYSTEM_DB_ENGINE - embed, postgres, mysql, mariadb, mongodb, redis, sqlserver
• SYSTEM_DB_HOST - System database host
• SYSTEM_DB_PORT - System database port
• SYSTEM_DB_NAME - System database name
• SYSTEM_DB_USER - System database username
• SYSTEM_DB_PASSWORD - System database password
• SYSTEM_DATABASE_URL - Complete system database connection string

Project Configuration:

• APITO_PROJECT_DB_ENGINE - postgres, mysql, mariadb, mongodb, redis, sqlserver
• PROJECT_DB_HOST - Project database host
• PROJECT_DB_PORT - Project database port
• PROJECT_DB_NAME - Project database name
• PROJECT_DB_USER - Project database username
• PROJECT_DB_PASSWORD - Project database password
• PROJECT_DATABASE_URL - Complete project database connection string

For more details, see Configuration Guide.

🚨 Troubleshooting

For common issues and solutions, see Troubleshooting Guide.

🔗 Useful Links

• Apito Platform: https://app.apito.io
• Documentation: https://docs.apito.io
• GitHub: https://github.com/apito-io/cli
• Support: https://github.com/apito-io/cli/issues

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Happy coding with Apito! 🎉