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

Website · Documentation · Discord

• 🆕 What's New
• 📦 Installation
• 🎯 Getting Started
• 📚 Command Reference
  • 🔧 System Management
    • init
    • init update
    • status
    • logs
  • 👤 Admin
    • admin password reset
  • 🗄️ Database Management
    • start --db
    • stop --db
    • restart --db
  • 🔌 Plugin Management
    • config
    • account
    • plugin
  • 📊 Monitoring & Observability
  • 🔧 Project Management
  • 🚀 Development & Execution
    • start
    • stop
    • restart
  • 🏗️ Building & Packaging
  • 🔄 Updates & Maintenance
• 🗂️ Project Structure
• ⚙️ Configuration
• 🚨 Troubleshooting
• 🔗 Useful Links
• 🤝 Contributing
• 📄 License

• 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

• Add from Registry: Install plugins with apito plugin add <name> from the official registry or any GitHub URL
• 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

• 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

• 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

• 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

• 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
• Admin Password Reset: apito admin password reset [email] with engine URL (default http://localhost:5050) and reset-token prompt
• Init Update: apito init update merges new default env keys into ~/.apito/bin/.env so existing users get new vars without re-running full apito init

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

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

# 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

apito --version

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

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

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)

Initializes and validates the Apito CLI system configuration.

Usage:

apito init

Features:

• Creates ~/.apito directory if it doesn't exist
• Sets up system configuration file with default values
• Database setup is now handled by apito start --db commands
• Validates system database configuration
• Checks mandatory environment variables (ENVIRONMENT, CORS_ORIGIN, COOKIE_DOMAIN, BRANKA_KEY)
• Validates database connection settings (host, port, user, password)
• Checks port availability (5050, 4000)
• Interactive configuration prompts for missing settings

What it checks:

• System database engine configuration (defaults to "coreDB")
• Database connection parameters (host, port, user, password, database name)
• Environment settings (local, development, staging, production)
• CORS and cookie domain configuration
• BRANKA_KEY generation (auto-generates if not provided)
• Port availability for Apito services (5050, 4000)

Examples:

# First-time setup
apito init

# Re-run to validate configuration
apito init

Adds any missing default env keys to your existing ~/.apito/bin/.env without overwriting existing values. Use this after upgrading the CLI when new env vars (e.g. APITO_ADMIN_RESET_SECRET) are introduced.

Usage:

apito init update

Behavior:

• Reads ~/.apito/bin/.env and compares it to the current default key set.
• Adds only keys that are missing, with their default values (e.g. a generated reset secret).
• Prints each added key; if nothing was missing, prints "Nothing to change."
• Does not modify or remove existing keys.

When to use:

• After a CLI upgrade that adds new env vars.
• When you see documentation or release notes mentioning new .env variables.

Examples:

apito init update
# Output (if keys were added):
# [SUCCESS] Updated ~/.apito/bin/.env
# [INFO]   Added: APITO_ADMIN_RESET_SECRET

# Output (if already up to date):
# [INFO] Nothing to change.

Default Configuration: The init command creates a .env file with these default values:

ENVIRONMENT=local
COOKIE_DOMAIN=localhost
CORS_ORIGIN=http://localhost:4000
PLUGIN_PATH=plugins
PUBLIC_KEY_PATH=keys/public.key
PRIVATE_KEY_PATH=keys/private.key
APITO_SYSTEM_DB_ENGINE=embed
BRANKA_KEY=<auto-generated-32-character-key>
APITO_ADMIN_RESET_SECRET=<auto-generated-12-char-secret>

BRANKA_KEY Behavior:

• If BRANKA_KEY is not set, a secure 32-character random key is automatically generated
• If BRANKA_KEY is already set, the existing value is preserved
• The generated key includes uppercase, lowercase, numbers, and special characters

Resets the password for a system user by email. The engine must be running. You provide the engine/API URL (or accept the default), paste the reset token (admin secret), and set a new password.

Usage:

apito admin password reset [email]
apito admin password reset -u <engine-url> [email]

Options:

• --url, -u - Engine/API base URL. If omitted, you are prompted; default is http://localhost:5050.

Flow:

1. Engine URL – From -u/--url, or prompt (default http://localhost:5050).
2. Email – From argument or prompt.
3. Reset token – Prompt: paste the admin reset secret (same value as APITO_ADMIN_RESET_SECRET in the engine’s .env).
4. Confirm – Confirm reset for the given email.
5. New password – Enter and confirm new password.

Examples:

# Interactive: URL prompt (default localhost:5050), then email, token, password
apito admin password reset

# With email on the command line
apito admin password reset [email protected]

# Specify engine URL (no URL prompt)
apito admin password reset -u https://api.myhost.com [email protected]

Note: The reset token is not read from your local env; you paste it when prompted (it must match the engine’s APITO_ADMIN_RESET_SECRET).

Shows whether services are running and displays database status when available.

Usage:

apito status [engine|console]

Features:

• Service Status: Shows running status for engine and console services
• Database Status: Automatically displays database container status when db-compose.yml exists
• Real-time Information: Shows current running/stopped status for all containers
• Docker Integration: Works seamlessly with Docker and local service modes
• Automatic Detection: Automatically detects and shows database status without additional flags

Examples:

# Show all services and database status
apito status

# Show specific service status
apito status engine
apito status console

Output Example:

[INFO] Database Status:
[SUCCESS]   apito-system-postgres: Running
[SUCCESS]   apito-project-postgres: Running
[WARNING] engine (docker) is not running
[WARNING] console (docker) is not running

View logs for Apito services (engine/console) and databases with real-time following and tail control.

Usage:

apito logs [engine|console] [--db system|project] [--follow] [--tail N]

Options:

• --db system|project - Show logs for specific database type
• --follow, -f - Follow log output in real-time
• --tail N, -n N - Show last N lines (default: 100)

Features:

• Service Logs: View logs for engine and console services
• Database Logs: View logs for system and project databases
• Real-time Following: Follow logs as they happen with --follow flag
• Tail Control: Control how many log lines to show with --tail flag
• Docker & Local Support: Works seamlessly in both Docker and local service modes
• Automatic Container Detection: Automatically finds the correct container for database logs

Examples:

# Database logs
apito logs --db system --tail 10
apito logs --db project --follow
apito logs --db system -f -n 5

# Service logs
apito logs engine --tail 50
apito logs console --follow
apito logs engine -f -n 100

# Default behavior (engine logs, last 100 lines)
apito logs

Output Examples:

# Database logs
[INFO] Showing logs for system database (apito-system-postgres):
2025-08-14 05:48:09.188 UTC [1] LOG: database system is ready to accept connections

# Service logs (when services are running)
[INFO] Showing logs for engine service:
# Log output from the engine container

Start system or project databases with interactive configuration and Docker integration.

Usage:

apito start --db system    # Start system database
apito start --db project  # Start project database

Features:

• Interactive Database Selection: Choose from PostgreSQL, MySQL, MariaDB, MongoDB, Redis, SQL Server
• Credential Options: Use default credentials or enter custom configuration
• Smart Configuration: Automatic detection of existing database settings
• Overwrite Protection: Confirmation prompts before overwriting existing configuration
• Persistent Volumes: Named Docker volumes for data persistence
• Consistent Naming: Container names follow apito-{dbType}-{engine} pattern

Database Engines Supported:

• PostgreSQL (port 5432) - Professional-grade relational database
• MySQL (port 3306) - Popular open-source database
• MariaDB (port 3307) - MySQL fork with enhanced features
• MongoDB (port 27017) - Document-based NoSQL database
• Redis (port 6379) - In-memory key-value store
• SQL Server (port 1433) - Microsoft's enterprise database

Configuration Options:

• Default Credentials: Automatic setup with apito user, generated password, and apito database
• Custom Configuration: Full control over host, port, username, password, and database name
• Engine-Specific Fields: Special configuration options for databases like MongoDB

Examples:

# Start system database with interactive setup
apito start --db system

# Start project database with interactive setup
apito start --db project

# Start services without database (default behavior)
apito start

Volume Naming Convention:

• System Database: apito-system-{engine}_data (e.g., apito-system-postgres_data)
• Project Database: apito-project-{engine}_data (e.g., apito-project-mysql_data)

Stop specific database services while keeping other services running.

Usage:

apito stop --db system    # Stop system database
apito stop --db project  # Stop project database

Examples:

# Stop only the system database
apito stop --db system

# Stop only the project database
apito stop --db project

# Stop all services (default behavior)
apito stop

Restart specific database services while keeping other services running.

Usage:

apito restart --db system    # Restart system database
apito restart --db project  # Restart project database

Examples:

# Restart only the system database
apito restart --db system

# Restart only the project database
apito restart --db project

# Restart all services (default behavior)
apito restart

Apito CLI provides a comprehensive plugin management system that allows you to create, deploy, update, and manage HashiCorp-based plugins with hot reload capabilities.

Configure accounts, server URLs, cloud sync keys, and other CLI settings for plugin management.

Usage:

apito config <command> [options]

Commands:

• set <key> <value> - Set a configuration value
• set <url|key> <value> - Set account-specific configuration with interactive selection
• set -a <account> <url|key> <value> - Set account-specific configuration with account flag
• set account <account-name> <url|key> <value> - Set account-specific configuration
• get [key] - Get configuration value(s)
• init - Initialize configuration interactively
• reset - Reset configuration to defaults

Configuration Keys:

• timeout - Request timeout in seconds (default: 30)
• default_plugin - Default plugin for operations
• mode - CLI run mode (docker or manual)
• default_account - Default account for plugin operations

Account Configuration:

• url - Apito server URL for the account
• key - Cloud sync key for the account

Interactive Account Selection:

When setting url or key without specifying an account, the CLI will show an interactive menu to choose from configured accounts:

# Interactive account selection (shows list of accounts)
apito config set key AQAAAABo3Wov1s_uv6RndWxE...
# Output:
# 📋 Select Account
# 1. local (default)
# 2. staging
# 3. production
# ? Choose account: [Use arrows to select]

# Direct account specification with flag
apito config set -a production key abc123...
apito config set --account staging url https://staging-api.apito.io

# Auto-selects if only one account exists
# Shows error if no accounts configured

Examples:

# Interactive configuration setup (creates accounts)
apito config init

# Interactive account selection for setting values
apito config set key abc123...        # Shows account selection menu
apito config set url https://api.apito.io  # Shows account selection menu

# Set account-specific values with -a flag (recommended)
apito config set -a production key abc123...
apito config set -a staging url https://staging-api.apito.io

# Set account-specific values (existing patterns still work)
apito config set account production url https://api.apito.io
apito config set production key abc123...

# Set default account
apito config set default_account production

# View all configuration including accounts
apito config get

# View specific setting
apito config get default_account

# View all accounts
apito config get account

# Reset all configuration
apito config reset

Manage multiple Apito accounts for different environments (production, staging, local, etc.).

Usage:

apito account <command> [options]

Commands:

• create <account-name> - Create a new account with interactive setup
• list - List all configured accounts
• select <account-name> - Set default account for plugin operations
• test <account-name> - Test account connection and credentials
• delete <account-name> - Delete an account configuration

Examples:

# Create a new account
apito account create production

# List all accounts
apito account list

# Test account connection
apito account test production

# Set default account
apito account select production

# Delete an account
apito account delete staging

Account Workflow:

# 1. Create accounts for different environments
apito account create production
apito account create staging
apito account create local

# 2. Configure each account (multiple ways)

# Method A: Using -a flag (recommended)
apito config set -a production url https://api.apito.io
apito config set -a production key prod-key-123

apito config set -a staging url https://staging-api.apito.io
apito config set -a staging key staging-key-456

apito config set -a local url http://localhost:5050
apito config set -a local key local-key-789

# Method B: Interactive selection (shows menu)
apito config set url https://api.apito.io  # Select from account list
apito config set key prod-key-123          # Select from account list

# Method C: Traditional syntax (still works)
apito config set account production url https://api.apito.io
apito config set production key prod-key-123

# 3. Test account connections
apito account test production
apito account test staging
apito account test local

# 4. Set default account
apito account select production

# 5. Use plugin commands (will use default account)
apito plugin deploy
apito plugin list

Create, deploy, update, and manage HashiCorp-based plugins with hot reload capabilities.

⚠️ Confirmation Required: Sensitive operations (deploy, update, delete, stop, restart) require confirmation and will display detailed information about the operation, including:

• Action being performed
• Plugin ID and version
• Target account and server URL
• Additional plugin details (language, type)

Usage:

apito plugin <command> [options]

Commands:

• add <plugin-name-or-github-url> - Add a plugin from the official registry or a GitHub repository (downloads latest release and deploys) ⚠️ Requires confirmation
• create - Create a new plugin scaffold
• build [directory] - Build plugin based on language configuration
• deploy [directory] - Deploy plugin to server ⚠️ Requires confirmation
• update <plugin-id> [directory] - Update existing plugin ⚠️ Requires confirmation
• list - List all plugins on server
• status <plugin-id> - Get plugin status
• delete <plugin-id> - Delete plugin from server ⚠️ Requires confirmation
• restart <plugin-id> - Restart plugin ⚠️ Requires confirmation
• stop <plugin-id> - Stop plugin ⚠️ Requires confirmation
• start <plugin-id> - Start plugin
• env - Show build environment information

Options:

• --account, -a - Specify account to use for plugin operations (optional, uses default if not specified)
• --replace - Delete existing plugin before deployment (for add and deploy commands)
• --dir, -d - Plugin directory (for deploy/update/build commands)
• --build, -b - Build method: system or docker (for build command, skips interactive prompt)
• --platform, -p - Target OS: linux, darwin, or windows (for build command, skips interactive prompt)
• --arch - Target architecture: amd64 or arm64 (for build command, skips interactive prompt)
• --type, -t - Go build type: debug, develop, or production (for build command, skips interactive prompt)

Features:

• Hot Reload: Deploy and update plugins without server restarts
• Process Isolation: HashiCorp go-plugin framework for fault tolerance
• Multi-language Support: Go, JavaScript, Python plugin development
• Secure Deployment: Cloud sync key authentication
• Real-time Status: Live plugin status monitoring and health checks
• Template Generation: Scaffold creation with best practices
• Confirmation System: Sensitive operations require explicit confirmation with detailed operation information

Add Plugin from Registry or GitHub:

# Add official plugin by name (from registry)
apito plugin add hc-auth-plugin

# Add plugin from GitHub URL
apito plugin add https://github.com/udhvabon/hc-prottoy-plugin
apito plugin add https://github.com/udhvabon/hc-prottoy-plugin.git

# Add with account and replace existing deployment
apito plugin add hc-auth-plugin --account production --replace

The add command fetches the latest release from GitHub, downloads the platform-specific binary (darwin/linux/windows, amd64/arm64), and deploys it. Use official plugin IDs from the registry or any GitHub repository URL that follows the plugin deployment docs.

Plugin Creation Workflow:

# 1. Configure CLI for plugin management
apito config init
# This creates your first account interactively

# 2. Create additional accounts for different environments (optional)
apito account create staging
apito config set account staging url https://staging-api.apito.io
apito config set account staging key staging-key-456

# 3. Set default account
apito account select production

# 4. Create new plugin scaffold
apito plugin create
# Follow prompts to select:
# - Plugin name (e.g., hc-my-awesome-plugin)
# - Language (Go, JavaScript, Python)
# - Plugin type (System, Project, Custom)

# 5. Develop your plugin
cd hc-my-awesome-plugin
# Edit main.go or main.js based on your language choice
# Modify config.yml with plugin metadata

# 6. Build plugin
apito plugin build

# 7. Deploy plugin to server (uses default account)
apito plugin deploy

# 8. Check plugin status
apito plugin status hc-my-awesome-plugin

Plugin Development:

# Add plugin from registry or GitHub (quickest way to get a plugin)
apito plugin add hc-auth-plugin
apito plugin add https://github.com/owner/hc-my-plugin

# Create plugin scaffold (for custom development)
apito plugin create
# > Enter plugin name: hc-file-processor
# > Select language: Go
# > Select type: System

# Build plugin (automatically detects language)
apito plugin build
# > Choose build method: System Go / Docker
# > (For Go) Choose build type: Debug / Development / Production

# Build plugin non-interactively (for automation/CI)
apito plugin build --build system --platform linux --arch amd64 --type production
apito plugin build -b docker -p linux --arch arm64 -t debug

# Deploy from current directory (requires confirmation)
apito plugin deploy

# Deploy from specific directory
apito plugin deploy ./path/to/plugin

# Deploy to specific account
apito plugin deploy --account staging
apito plugin deploy -a production

# Force deploy (delete existing before deploy)
apito plugin deploy -a udbhabon --force
apito plugin deploy -a udbhabon -f
apito plugin deploy -a udbhabon --replace

# Update existing plugin (requires confirmation)
apito plugin update hc-file-processor

# List plugins from specific account
apito plugin list --account staging
apito plugin list -a production

# Check plugin status from specific account
apito plugin status hc-file-processor --account staging

Plugin Build System:

The build system automatically detects the plugin language from config.yml and provides appropriate build options. It supports both interactive and non-interactive modes, similar to the --account flag pattern.

Build Modes:

• Interactive Mode (default): When no flags are provided, the CLI shows interactive prompts for build options
• Non-Interactive Mode: When flags are provided, the CLI skips prompts and uses flag values directly

Go Plugins:

# Build Go plugin with interactive options
apito plugin build
# Options:
# - System vs Docker build
# - Target platform (Linux AMD64, Linux ARM64, macOS, Windows, Host OS)
# - Build type: Debug / Development / Production

# Build Go plugin non-interactively (for automation/CI/CD)
apito plugin build --build system --platform linux --arch amd64 --type production
apito plugin build -b docker -p linux --arch arm64 -t debug
apito plugin build --build system -p darwin --arch arm64 --type develop

# Partially interactive (only build method specified)
apito plugin build --build docker
# Will still prompt for platform and build type

# Examples of actual build commands used:
# Debug: go build -gcflags="all=-N -l" -o hc-plugin-name .
# Development: GOOS=linux GOARCH=amd64 go build -o hc-plugin-name .
# Production: CGO_ENABLED=0 go build -ldflags "-s" -a -o hc-plugin-name .

Build Flags:

• --build, -b: Build method (system or docker)

  • If not specified, prompts interactively
  • If system is specified but runtime not available, falls back to Docker with warning

• --platform, -p: Target operating system (linux, darwin, windows)

  • If not specified, prompts interactively
  • Must be used with --arch for non-interactive mode

• --arch: Target architecture (amd64, arm64)

  • If not specified with --platform, uses host architecture
  • Validates platform/arch combinations

• --type, -t: Go build type (debug, develop, production)

  • If not specified, prompts interactively
  • Only applies to Go plugins
  • Accepts: debug, develop/development, production

JavaScript Plugins:

# Build JavaScript plugin
apito plugin build
# Automatically runs:
# - npm install (install dependencies)
# - node --check index.js (syntax validation)

Python Plugins:

# Build Python plugin
apito plugin build
# Automatically runs:
# - pip3 install -r requirements.txt (if exists)
# - python3 -m py_compile main.py (syntax validation)

Build Environment:

# Check available build tools
apito plugin env
# Shows status of:
# - Go runtime
# - Node.js runtime
# - Python runtime
# - Docker availability
# - System architecture

Plugin Management:

# List all plugins
apito plugin list

# Get detailed plugin status
apito plugin status hc-file-processor

# Control plugin lifecycle (requires confirmation)
apito plugin restart hc-file-processor
apito plugin stop hc-file-processor
apito plugin start hc-file-processor

# Remove plugin (requires confirmation)
apito plugin delete hc-file-processor

Plugin Configuration (config.yml):

plugin:
  id: "hc-your-plugin-name"
  language: "go" # go, js, python
  title: "Your Plugin Title"
  icon: "🔌"
  description: "Plugin description"
  type: "system" # system, project, custom
  role: "custom"
  exported_variable: "NormalPlugin"
  enable: true
  debug: false
  version: "1.0.0"
  author: "Your Name"
  repository_url: "https://github.com/your/repo"
  branch: "main"
  binary_path: "hc-your-plugin-name"
  handshake_config:
    protocol_version: 1
    magic_cookie_key: "APITO_PLUGIN"
    magic_cookie_value: "apito_plugin_magic_cookie_v1"
  env_vars:
    - key: "PLUGIN_DEBUG_MODE"
      value: "false"

Plugin Types:

• System Plugins: Core functionality, authentication, storage drivers
• Project Plugins: Project-specific business logic and workflows
• Custom Plugins: User-defined functionality and integrations

Supported Languages:

• Go: Native HashiCorp go-plugin support with maximum performance
• JavaScript: Node.js-based plugins with npm ecosystem access
• Python: Python plugins with pip package management

The CLI now provides comprehensive visibility into your Apito infrastructure:

• Service Status: Monitor engine and console service health
• Database Status: Real-time database container status monitoring
• Automatic Detection: Database status automatically displayed when available
• Docker Integration: Seamless integration with Docker container management

Access logs for all components with powerful filtering and real-time capabilities:

• Service Logs: Engine and console application logs
• Database Logs: Database container logs with engine-specific formatting
• Real-time Following: Follow logs as they happen for live debugging
• Tail Control: View specific numbers of log lines for focused analysis
• Multi-mode Support: Works in both Docker and local service modes

# Check overall system health
apito status

# Monitor specific services
apito status engine
apito status console

# View real-time logs
apito logs --db system --follow
apito logs engine --follow

# Analyze recent activity
apito logs --db project --tail 100
apito logs console --tail 50

• Development Debugging: Follow logs in real-time during development
• Production Monitoring: Check service health and database status
• Troubleshooting: Analyze recent logs for error investigation
• Performance Analysis: Monitor database and service performance
• Deployment Verification: Confirm services are running correctly after deployment

Creates new projects, functions, or models via API calls to the Apito server.

Usage:

apito create <resource> [options]

Resources:

• project - Create a new Apito project via API
• function - Create a new function (coming soon)
• model - Create a new data model (coming soon)

Options:

• --name, -n - Name of the resource
• --project, -p - Project name (alternative to --name)

Features:

• Interactive project creation with prompts
• Database type selection with visual icons
• Automatic SYNC_TOKEN management
• HTTP API integration with authentication
• Real-time project creation on Apito server

Database Options:

• Embed & SQL (mdi:database) - Default embedded database
• MySQL (logos:mysql) - MySQL database
• MariaDB (logos:mariadb) - MariaDB database
• PostgreSQL (logos:postgresql) - PostgreSQL database
• Couchbase (logos:couchbase) - Couchbase database
• Oracle (logos:oracle) - Oracle database
• Firestore (logos:firebase) - Firebase Firestore
• MongoDB (logos:mongodb) - MongoDB database
• DynamoDB (logos:aws-dynamodb) - AWS DynamoDB

Examples:

# Create a new project with prompts
apito create project

# Create a project with name flag
apito create project -p my-ecommerce-app

# Create a project with name flag (alternative)
apito create project -n my-ecommerce-app

Starts the Apito engine and console with automatic setup and downloads.

Usage:

apito start [--db system|project]

Options:

• --db system - Start system database with interactive setup
• --db project - Start project database with interactive setup

Features:

• Run Modes: Docker (default) or Manual, stored in ~/.apito/config.yml
• Docker Mode: Uses compose with persistent volumes and .env mounted inside the engine container
• Manual Mode: Downloads binaries, installs Caddy, and manages processes with PID/log files
• Port Management: Checks 5050/4000 (Manual mode only)
• Graceful Shutdown: Stops all services on Ctrl+C
• Database Integration: Optional database startup with --db flag

What it does:

1. Loads run mode from ~/.apito/config.yml (defaults to Docker)
2. Database Setup (if --db flag specified):
   • Interactive database engine selection
   • Credential configuration (default or custom)
   • Docker container creation with persistent volumes
   • Configuration saved to ~/.apito/bin/.env
3. Service Startup:
   • Docker mode: Compose up engine and console with required volumes
   • Manual mode: Port check, download components, start services
4. Waits for interrupt to stop services

Examples:

# Start Apito with automatic setup
apito start

# Start with system database
apito start --db system

# Start with project database
apito start --db project

Access URLs:

• Engine API: http://localhost:5050
• Console UI: http://localhost:4000

System Requirements:

• Internet connection for downloading components
• Write permissions to ~/.apito/ directory
• Port 5050 and 4000 available
• Docker and Docker Compose (for database features)

Stops one or more Apito services.

Usage:

apito stop [engine|console|all] [--db system|project]

Options:

• --db system - Stop only the system database
• --db project - Stop only the project database

Examples:

# Stop everything
apito stop

# Stop only engine
apito stop engine

# Stop only console
apito stop console

# Stop only system database
apito stop --db system

# Stop only project database
apito stop --db project

Restarts one or more Apito services.

Usage:

apito restart [engine|console|all] [--db system|project]

Options:

• --db system - Restart only the system database
• --db project - Restart only the project database

Examples:

# Restart everything
apito restart

# Restart only engine
apito restart engine

# Restart only console
apito restart console

# Restart only system database
apito restart --db system

# Restart only project database
apito restart --db project

Builds your project for different deployment targets.

Usage:

apito build <target> -p <project> [options]

Targets:

• docker - Build Docker image
• zip - Create deployment package

Options:

• --project, -p - Project name (required)
• --tag, -t - Docker image tag (optional, for docker builds)

Examples:

# Build Docker image
apito build docker -p my-ecommerce-app
apito build docker -p my-ecommerce-app -t v1.0.0

# Create ZIP package
apito build zip -p my-ecommerce-app

Update Apito engine, console, or the CLI itself.

Usage:

apito update <engine|console|self> [-v <version>]

Examples:

# Update engine to latest version
apito update engine

# Update console to a specific version
apito update console -v v1.2.3

# Update the CLI itself to the latest version
apito update self

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)

Logging & Monitoring:

• Service Logs: Local service logs stored in ~/.apito/logs/ (Manual mode)
• Container Logs: Docker container logs accessible via apito logs command
• Database Logs: Database container logs with real-time following capability
• Status Monitoring: Real-time service and database status via apito status

The CLI manages two types of configuration:

• 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)
  • account_name - Account configuration
    • server_url - Apito server URL for the account
    • cloud_sync_key - Authentication key for the account

Setting Account Configuration:

You can configure accounts using three methods:

1. Interactive Selection (recommended for beginners):

   apito config set key <value>  # Shows account selection menu
   apito config set url <value>  # Shows account selection menu

2. Using -a Flag (recommended for scripts):

   apito config set -a production key <value>
   apito config set -a staging url <value>

3. Traditional Syntax (still supported):

   apito config set account production url <value>
   apito config set production key <value>

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

• ENVIRONMENT - local/development/staging/production
• COOKIE_DOMAIN - e.g., localhost
• CORS_ORIGIN - e.g., http://localhost:4000
• BRANKA_KEY - Generated secret key
• APITO_ADMIN_RESET_SECRET - Secret for admin password reset (used when running apito admin password reset; paste this when prompted for "reset token")
• 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

• 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

• SERVE_PORT - Engine port (default 5050)
• CACHE_*, KV_ENGINE, AUTH_SERVICE_PROVIDER, TOKEN_TTL
• CADDY_PATH - Absolute path to caddy (managed by CLI)

• Embedded: boltDB (default)
• External: PostgreSQL, MySQL, MariaDB, MongoDB, Redis, SQL Server

• External: PostgreSQL, MySQL, MariaDB, MongoDB, Redis, SQL Server
• Cloud: Firestore (alpha), DynamoDB (alpha)

• System Database: apito-system-{engine} (e.g., apito-system-postgres)
• Project Database: apito-project-{engine} (e.g., apito-project-mysql)

• System Database: apito-system-{engine}_data (e.g., apito-system-postgres_data)
• Project Database: apito-project-{engine}_data (e.g., apito-project-mysql_data)

• Docker Engine 20.10+
• Docker Compose v2 (recommended) or v1
• Docker daemon running

The CLI automatically manages engine and console versions with smart update detection:

1. During apito init (Docker mode):

   • Automatically fetches latest versions from GitHub releases
   • Stores versions in ~/.apito/config.yml
   • Generates docker-compose.yml with specific version tags

2. During apito start (Docker mode):

   • Checks for newer versions available on GitHub
   • Prompts user if updates are found
   • Allows selective updates (engine only, console only, or both)
   • Automatically pulls new Docker images
   • Regenerates docker-compose.yml with updated versions

Versions are stored in ~/.apito/config.yml:

mode: docker
engine_version: v1.3.1
console_version: v2.5.0

# Start will check for updates
$ apito start

# If updates are available, you'll see:
🆕 Updates Available

  Engine: v1.3.0 → v1.3.1
  Console: v2.4.0 → v2.5.0

? Choose update action:
  ▸ Update Engine (v1.3.0 → v1.3.1)
    Update Console (v2.4.0 → v2.5.0)
    Update Both
    Skip Updates

# After selecting, the CLI will:
✓ Pulling Docker image: ghcr.io/apito-io/engine:v1.3.1
✓ Successfully pulled ghcr.io/apito-io/engine:v1.3.1
✓ Updated engine to v1.3.1
✓ docker-compose.yml updated

• Consistent Deployments: Version pinning prevents unexpected breaking changes
• Easy Rollback: Simply edit config.yml to downgrade if needed
• Transparent Updates: Always know what version you're running
• Offline-Friendly: Uses cached images if GitHub is unreachable

You can manually set versions in config.yml:

engine_version: v1.2.0 # Downgrade to specific version
console_version: latest # Use latest tag

Then regenerate docker-compose.yml:

apito init  # Will respect your manual version settings

Permission Denied Error:

# The installer will automatically handle permissions
# If you encounter issues, run with sudo:
sudo ./install.sh

Docker Not Available:

# Check Docker installation
docker --version

# Check Docker Compose
docker compose version

# Check Docker daemon status
docker info

# Install Docker if needed:
# macOS: https://docs.docker.com/desktop/install/mac-install/
# Linux: https://docs.docker.com/engine/install/

Database Connection Issues:

# Check database container status
docker ps | grep apito

# View database logs using the new logs command
apito logs --db system --tail 20
apito logs --db project --follow

# View database logs directly (alternative)
docker logs apito-system-postgres

# Check volume persistence
docker volume ls | grep apito

# Restart database service
apito restart --db system

Project Not Found:

# List all projects to see available ones
apito list

# Create a new project if needed
apito create project -n my-new-project

Engine or Console Won't Start:

# Check if services are running and view logs
apito status

# Stop services
apito stop

# Then try running again
apito start

Configuration Overwrite Issues:

# The CLI now asks for confirmation before overwriting
# If you need to reset configuration:
rm ~/.apito/bin/.env
apito init

Logs and Monitoring Issues:

# Check if database containers are running
apito status

# View real-time database logs
apito logs --db system --follow
apito logs --db project --follow

# View last N lines of logs
apito logs --db system --tail 50
apito logs --db project --tail 50

# Check service logs
apito logs engine --tail 100
apito logs console --follow

# If logs command fails, check container status
docker ps --filter "name=apito-"

Volume Management:

# List all apito volumes
docker volume ls | grep apito

# Backup a specific database volume
docker run --rm -v apito-system-postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_backup.tar.gz -C /data .

# Remove a specific database volume (after stopping container)
docker volume rm apito-system-postgres_data

Plugin Management Issues:

# Plugin configuration issues
apito config get                     # Check CLI configuration
apito account list                   # List all accounts
apito config init                    # Reconfigure CLI settings

# Plugin deployment failures
apito plugin list                    # Check server connectivity
apito plugin status <plugin-id>     # Check specific plugin status

# Account-related issues
apito account create <name>          # Create new account
apito account test <name>            # Test account connection
apito account select <name>          # Set default account

# Set account configuration (multiple methods)
apito config set -a <name> url <url>     # Using -a flag (recommended)
apito config set -a <name> key <key>     # Using -a flag (recommended)
apito config set url <url>               # Interactive selection
apito config set key <key>               # Interactive selection
apito config set account <name> url <url>  # Traditional syntax
apito config set <name> key <key>          # Traditional syntax

# Plugin server connection issues
curl -H "Authorization: Bearer <sync-key>" \
     https://your-server.com/plugin/v2/health

# Check plugin configuration file
cat hc-your-plugin/config.yml       # Validate YAML syntax

Plugin Development Issues:

# Plugin creation failures
apito plugin create                  # Try creating new scaffold

# Build environment issues
apito plugin env                     # Check available build tools

# Build issues (for Go plugins)
cd hc-your-plugin
apito plugin build                   # Use CLI build system (interactive)
# Non-interactive build for automation/CI:
apito plugin build --build system --platform linux --arch amd64 --type production
# Alternative manual build:
go mod tidy                         # Fix dependencies
go build -o hc-your-plugin .        # Test local build

# Build issues (for JavaScript plugins)
cd hc-your-plugin-js
npm install                         # Install dependencies manually
node --check index.js               # Check syntax
apito plugin build                  # Use CLI build system (interactive)
apito plugin build --build system   # Non-interactive: use system Node.js

# Build issues (for Python plugins)
cd hc-your-plugin-py
pip3 install -r requirements.txt    # Install dependencies manually
python3 -m py_compile main.py       # Check syntax
apito plugin build                  # Use CLI build system (interactive)
apito plugin build --build docker   # Non-interactive: force Docker build

# Docker build issues
docker --version                    # Check Docker availability
apito plugin build                  # Interactive: select system build if Docker fails
apito plugin build --build system   # Non-interactive: force system build

# Plugin deployment authentication
apito config set cloud_sync_key <your-key>  # Update auth key
apito config set server_url <your-url>      # Update server URL

Plugin Runtime Issues:

# Plugin not starting
apito plugin restart <plugin-id>    # Restart plugin
apito plugin status <plugin-id>     # Check error messages

# Plugin performance issues
apito plugin stop <plugin-id>       # Stop plugin
apito plugin start <plugin-id>      # Start plugin fresh

# Account switching for different environments
apito account test staging          # Test staging account first
apito plugin deploy --account staging  # Deploy to staging (requires confirmation)
apito plugin deploy -a production      # Deploy to production (requires confirmation)

# Or switch default account
apito account select staging        # Switch to staging account
apito plugin deploy                 # Deploy to staging (uses default, requires confirmation)
apito account select production     # Switch back to production
apito plugin deploy                 # Deploy to production (uses default, requires confirmation)

# Plugin logs (server-side)
# Check your Apito server logs for plugin-specific errors

• 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

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

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

Happy coding with Apito! 🎉