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: Unified apt_ access token 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
Silent configuration: if ~/.apito/config.yml or ~/.apito/bin/.env is missing, the CLI writes the defaults and prints one warning

📦 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. Configuration

The first command that needs ~/.apito writes config.yml, bin/.env.engine, and bin/.env.console when they are missing, then prints one warning and continues. There is no setup prompt. .env.engine holds the engine settings, including a generated BRANKA_KEY and signing-key paths. .env.console holds the console URLs. apito start mounts both files into Studio and mounts ~/.apito/db at /data.

Pin a Studio image with studio_version in ~/.apito/config.yml. Leave it empty to use the latest published ghcr.io/apito-io/studio tag.

1. Connect an account and create a project

apito account create local
apito create

apito create creates a project on a connected account through the system API. One account is selected automatically. Several accounts use the same picker as apito sync. Zero accounts asks you to connect one first. The account can be local Studio or cloud. Plugin scaffolds stay on apito plugin create.

2. Start Studio

apito start

This prepares ~/.apito when the files are missing, pulls ghcr.io/apito-io/studio, and runs the apito-studio container. The console is at http://localhost:5055. The database stays in ~/.apito/db. apito stop, apito restart, apito status, and apito logs talk to that container.

📚 Command Reference

🔧 System Management

Configuration

~/.apito/config.yml, ~/.apito/bin/.env.engine, and ~/.apito/bin/.env.console are created with defaults the first time a command needs them. The CLI prints one warning and continues. .env.engine is also copied to ~/.apito/bin/.env. Set studio_version to pin ghcr.io/apito-io/studio; leave it empty to track the latest published tag.

`migrate` - Copy a database onto an existing destination

Copies one project's physical database, or one SaaS tenant database, from a source account onto a destination account. The destination project must already exist. If the schema hashes differ, the command stops and tells you to run apito sync --type schema first. This is not a schema migration and it is not apito sync.

Usage:

apito migrate

A remote destination needs --allow-push and a second confirmation.

Output (nothing to do):

[INFO] Nothing to change.


**Default Configuration:**
The first run writes `~/.apito/bin/.env.engine` and `~/.apito/bin/.env.console`. The engine file points the database at `/data` inside the container, which is the `~/.apito/db` volume. `BRANKA_KEY` is a generated 32-character key. An existing key is kept. The engine listens on port `5051` inside the container. The console file points the UI at `http://localhost:5055`. The first start prints `oss@apito.io` and a random admin password. Later starts keep that password.

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

```bash
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 admin@example.com

# Specify engine URL (no URL prompt)
apito admin password reset -u https://api.myhost.com admin@example.com

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, access tokens (apt_...), 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 - Apito access token (apt_...) for the account, generated in Console → Access Token. Legacy cli-/sdk-/mcp- prefixed keys are retired and rejected with TOKEN_FORMAT_RETIRED.

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: Unified apt_ access token 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

🔄 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, access token)

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 - Apito access token (apt_...) 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:

When configuration is first written:
- 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

studio_version in the same file pins ghcr.io/apito-io/studio. Leave it empty to use the latest published tag. The next apito start pulls that tag.

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

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-apt_-token>  # Update access token
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

Sync a local project to Apito Cloud

Both engines keep schema drafts until you publish. Cloud adds managed collaboration and production publish.

apito account create local
apito account create production
# apt_ tokens on both accounts
apito sync --from local --to production --dry-run
apito sync --from local --to production --yes

Then open the Cloud console and publish the staged schema. Optional later steps copy content and functions. Docker is the default run mode and pulls ghcr.io/apito-io/engine and ghcr.io/apito-io/console. An experimental local binary is available from GitHub release zips.

🤝 Contributing

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

📄 License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details. The engine and console are Fair Source (FSL-1.1-ALv2) and convert to Apache 2.0 two years after each release. This CLI is Apache 2.0 now.

Happy coding with Apito! 🎉

Name		Name	Last commit message	Last commit date
.cursor/rules		.cursor/rules
.github/workflows		.github/workflows
.knowledge		.knowledge
.memory		.memory
Formula		Formula
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CNAME		CNAME
LICENSE		LICENSE
README.md		README.md
admin.go		admin.go
config.go		config.go
config.yml.example		config.yml.example
create.go		create.go
db_setup.go		db_setup.go
docker_manager.go		docker_manager.go
dump.go		dump.go
dump_preflight.go		dump_preflight.go
dump_test.go		dump_test.go
dump_transport.go		dump_transport.go
env.go		env.go
go.mod		go.mod
go.sum		go.sum
handover.go		handover.go
init.go		init.go
install.sh		install.sh
logs.go		logs.go
main.go		main.go
plugin_add.go		plugin_add.go
plugin_build.go		plugin_build.go
plugin_deploy.go		plugin_deploy.go
self_upgrade.go		self_upgrade.go
service_manager.go		service_manager.go
start.go		start.go
status.go		status.go
stop.go		stop.go
studio_env.go		studio_env.go
studio_env_test.go		studio_env_test.go
studio_runtime.go		studio_runtime.go
sync.go		sync.go
sync_apply.go		sync_apply.go
sync_apply_test.go		sync_apply_test.go
sync_content.go		sync_content.go
sync_deps.go		sync_deps.go
sync_diff.go		sync_diff.go
sync_diff_test.go		sync_diff_test.go
sync_filesystem_test.go		sync_filesystem_test.go
sync_function_diff.go		sync_function_diff.go
sync_function_fs.go		sync_function_fs.go
sync_functions.go		sync_functions.go
sync_functions_test.go		sync_functions_test.go
sync_graphql.go		sync_graphql.go
sync_graphql_headers_test.go		sync_graphql_headers_test.go
sync_live_nested_test.go		sync_live_nested_test.go
sync_nested_order_test.go		sync_nested_order_test.go
sync_plan.go		sync_plan.go
sync_schema.go		sync_schema.go
sync_schema_fs.go		sync_schema_fs.go
sync_schema_fs_test.go		sync_schema_fs_test.go
sync_schema_merge.go		sync_schema_merge.go
sync_schema_merge_test.go		sync_schema_merge_test.go
sync_select_test.go		sync_select_test.go
sync_validate.go		sync_validate.go
sync_validate_prottoy_test.go		sync_validate_prottoy_test.go
token_format.go		token_format.go
uninstall.sh		uninstall.sh
update.go		update.go
utility.go		utility.go
version_manager.go		version_manager.go

Latest commit

History

Folders and files

Repository files navigation

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

1. Connect an account and create a project

2. Start Studio

📚 Command Reference

🔧 System Management

Configuration

migrate - Copy a database onto an existing destination

Output (nothing to do):

[INFO] Nothing to change.

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

🔄 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

Sync a local project to Apito Cloud

🤝 Contributing

📄 License

About

Resources

`migrate` - Copy a database onto an existing destination

`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

`update` - Update Components

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

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