cli

Apito CLI

One Apache-licensed binary for a local engine and Apito Cloud. Cloud-only commands stay in the help text and fail closed until the connected account’s server reports the capability.

apito login asks the local engine at http://localhost:5055 for a code, then opens the console at http://localhost:4055/cli. Cloud uses https://api.apito.io and opens the console URL that server returns. Custom asks for the server URL and an apt_ token. The token is stored outside config.yml. Project keys (ak_) are separate and are shown once at creation.

apito mcp connect uses the same Local, Cloud, or Custom choice and opens /mcp. It stores a separate read-only MCP token. apito mcp serve stays a foreground process for Cursor or Claude and does not put that token in the generated client config.

apito login [name]
apito account list|select|test|remove
apito project list|open
apito key project list|create|revoke
apito mcp connect [name]
apito mcp update
apito mcp config --client cursor|claude
apito mcp serve
apito gen --language typescript|go --framework astro|react|none
apito tenant list|create
apito client invite|status
apito backup list|run
apito restore preview|apply

apito gen writes TypeScript/TSX or Go. It does not emit plain JavaScript or Python. --framework none writes types and an SDK without React Query hooks. Generated files and .apito-gen-manifest.json do not contain tokens. apito handover moves a self-hosted project. apito client is a Cloud engagement and is separate.

The contract is .knowledge/features/cli-contract.md.

Apito Logo

Earlier command reference

The Apito CLI installs and runs a local engine and console, and talks to Apito Cloud. Supported databases are SQLite, PostgreSQL, MySQL, MariaDB, and MongoDB. DynamoDB, Oracle, and Cassandra are coming soon.

Website · Documentation · Discord

📋 Table of Contents

License Release Go Report Card Build Status

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

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:4055. The engine 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 `5055` inside the container. Nginx listens on `4055` and proxies API paths to that engine port. The console file points the UI at `http://localhost:4055`. The first start prints `[email protected]` 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:

Flow:

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

Examples:

# Interactive: URL prompt (default localhost:5055), 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:

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:

Features:

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:

Database Engines Supported:

DynamoDB, Oracle, and Cassandra are coming soon.

Configuration Options:

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:

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:

Configuration Keys:

Account Configuration:

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:

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

Usage:

apito plugin <command> [options]

Commands:

Options:

Features:

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:

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:

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:

Supported Languages:

📊 Monitoring & Observability

Enhanced Status Monitoring

The CLI now provides comprehensive visibility into your Apito infrastructure:

Comprehensive Logging System

Access logs for all components:

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

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

Options:

Features:

Database Options:

DynamoDB, Oracle, and Cassandra are coming soon.

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:

Features:

What it does:

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

Examples:

# Start Apito with automatic setup
apito start

# Start with system database
apito start --db system

# Start with project database
apito start --db project

Access URLs:

System Requirements:

stop - Stop Services

Stops one or more Apito services.

Usage:

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

Options:

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:

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:

⚙️ Configuration

Environment Variables

The CLI manages two types of configuration:

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

Setting Account Configuration:

You can configure accounts using three methods:

  1. Interactive Selection (recommended for beginners):

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

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

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

  3. Traditional Syntax (still supported):

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

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

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

System Configuration:

Project Configuration:

Service Configuration:

Database Support

System Database:

DynamoDB, Oracle, and Cassandra are coming soon.

Project Database:

DynamoDB, Oracle, and Cassandra are coming soon.

Docker Integration

Container Naming Convention:

Volume Naming Convention:

Docker Requirements:

Version Management

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

How It Works:

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

  2. During apito start (Docker mode):

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

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:

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

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 CLI is licensed under Apache 2.0 (see LICENSE). The engine, console and Studio are AGPL-3.0.

Happy coding with Apito! 🎉

This site is open source. Improve this page.