cli

Apito Logo

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.

Website · Documentation · Discord

🆕 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

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

✨ 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
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

📦 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

🔧 System Management

`init` - Initialize Apito CLI System

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

`init update` - Merge New Env Keys Into System .env

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

👤 Admin

`admin password reset` - Reset User Password by Email

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:

Engine URL – From -u/--url, or prompt (default http://localhost:5050).
Email – From argument or prompt.
Reset token – Prompt: paste the admin reset secret (same value as APITO_ADMIN_RESET_SECRET in the engine’s .env).
Confirm – Confirm reset for the given email.
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).

`status` - Show Service and Database Status

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

`logs` - View Service and Database Logs

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

🗄️ Database Management

`start --db` - Start Database Services

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 --db` - Stop Database Services

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 --db` - Restart Database Services

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

🔌 Plugin Management

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

`config` - Manage CLI Configuration

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

`account` - Manage Multiple Accounts

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

`plugin` - Manage HashiCorp Plugins

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

📊 Monitoring & Observability

Enhanced Status Monitoring

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

Comprehensive Logging System

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

Monitoring Commands

# 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

Use Cases

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

🔧 Project Management

`create` - Create New Resources

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

🚀 Development & Execution

`start` - Start Apito Engine and Console

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:

Loads run mode from ~/.apito/config.yml (defaults to Docker)
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
Service Startup:
- Docker mode: Compose up engine and console with required volumes
- Manual mode: Port check, download components, start services
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)

`stop` - Stop Services

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

`restart` - Restart Services

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

🏗️ Building & Packaging

`build` - Build 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

🔄 Updates & Maintenance

`update` - Update Components

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

🗂️ 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)

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

⚙️ Configuration

Environment Variables

The CLI manages two types of 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)
- 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:

Interactive Selection (recommended for beginners):

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

Using -a Flag (recommended for scripts):

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

Traditional Syntax (still supported):

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

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_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

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

Service Configuration:

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

Database Support

System Database:

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

Project Database:

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

Docker Integration

Container Naming Convention:

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

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)

Docker Requirements:

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

Version Management

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

How It Works:

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

Version Storage:

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

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

Update Workflow:

# 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

Benefits:

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

Manual Version Control:

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

🚨 Troubleshooting

Common Issues

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

🔗 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! 🎉

This site is open source. Improve this page.

cli

Apito CLI

📋 Table of Contents

🆕 What’s New in Latest Version

🔄 Automatic Version Management

🔌 Plugin Management System

✨ Enhanced Database Management

🐳 Improved Docker Integration

⚙️ Enhanced Configuration System

🔧 CLI Command Enhancements

📦 Installation

Homebrew (macOS and Linux)

Quick Install (Linux & macOS)

Manual Install

Verify Installation

🎯 Getting Started

0. Initialize Apito CLI (First Time Setup)

1. Create Your First Project

2. Start Apito Engine and Console

📚 Command Reference

🔧 System Management

init - Initialize Apito CLI System

init update - Merge New Env Keys Into System .env

👤 Admin

admin password reset - Reset User Password by Email

status - Show Service and Database Status

logs - View Service and Database Logs

🗄️ Database Management

start --db - Start Database Services

stop --db - Stop Database Services

restart --db - Restart Database Services

🔌 Plugin Management

config - Manage CLI Configuration

account - Manage Multiple Accounts

plugin - Manage HashiCorp Plugins

📊 Monitoring & Observability

Enhanced Status Monitoring

Comprehensive Logging System

Monitoring Commands

Use Cases

🔧 Project Management

create - Create New Resources

🚀 Development & Execution

start - Start Apito Engine and Console

stop - Stop Services

restart - Restart Services

🏗️ Building & Packaging

build - Build Project

🔄 Updates & Maintenance

update - Update Components

🗂️ Project Structure

⚙️ Configuration

Environment Variables

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

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

System Configuration:

Project Configuration:

Service Configuration:

Database Support

System Database:

Project Database:

Docker Integration

Container Naming Convention:

Volume Naming Convention:

Docker Requirements:

Version Management

How It Works:

Version Storage:

Update Workflow:

Benefits:

Manual Version Control:

🚨 Troubleshooting

Common Issues

🔗 Useful Links

🤝 Contributing

📄 License

`init` - Initialize Apito CLI System

`init update` - Merge New Env Keys Into System .env

`admin password reset` - Reset User Password by Email

`status` - Show Service and Database Status

`logs` - View Service and Database Logs

`start --db` - Start Database Services

`stop --db` - Stop Database Services

`restart --db` - Restart Database Services

`config` - Manage CLI Configuration

`account` - Manage Multiple Accounts

`plugin` - Manage HashiCorp Plugins

`create` - Create New Resources

`start` - Start Apito Engine and Console

`stop` - Stop Services

`restart` - Restart Services

`build` - Build Project

`update` - Update Components

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

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