Commands
Complete reference for all iop CLI commands
Commands
Complete reference for all available iop CLI commands.
iop init
Initialize a new iop project with configuration files.
Usage
iop init [flags]
Flags
--help
- Show help message--non-interactive
- Skip prompts, use defaults--name <name>
- Set project name (non-interactive mode)
Examples
iop init # Interactive setup
iop init --non-interactive # Use defaults
iop init --name my-app # Set name non-interactively
What it does
- Creates
iop.yml
with configuration template - Creates
.iop/secrets
file for sensitive environment variables - Automatically adds
.iop/secrets
to.gitignore
for security
Generated Files
iop.yml
:
name: my-project
ssh:
username: iop
apps:
web:
build:
context: .
dockerfile: Dockerfile
server: your-server-ip
environment:
plain:
- NODE_ENV=production
secret:
- DATABASE_URL
proxy:
app_port: 3000
health_check:
path: /api/health
# Example service (uncomment and configure as needed)
# services:
# db:
# image: postgres:15
# server: your-server-ip
# ports:
# - "5432:5432"
# environment:
# plain:
# - POSTGRES_USER=postgres
# - POSTGRES_DB=my-project
# secret:
# - POSTGRES_PASSWORD
# volumes:
# - ./pgdata:/var/lib/postgresql/data
.iop/secrets
:
# Add your secret environment variables here
# Example:
# DATABASE_URL=postgres://user:password@localhost:5432/mydb
# POSTGRES_PASSWORD=supersecret
# API_KEY=your-api-key
iop
(Deploy - Default Command)
Deploy applications and services to configured servers. This is the default command when no command is specified.
Usage
iop [entry-names...] [flags] # Default - no 'deploy' needed
iop deploy [entry-names...] [flags] # Explicit command
Flags
--services
- Deploy services only (skip apps)--verbose
- Show detailed deployment progress--help
- Show help message
Examples
iop # Deploy all apps and services
iop web api # Deploy specific apps/services
iop --services # Deploy only services
iop --verbose # Deploy with detailed output
Deployment Process
- Configuration validation - Load and validate iop.yml
- Git status check - Ensure working directory is clean
- Infrastructure setup - Automatically sets up servers if needed (no separate setup command required)
- Image building - Build Docker images locally for apps with build configuration
- Image transfer - Compress and transfer images via SSH (no registry needed)
- Zero-downtime deployment - Blue-green deployment for apps, direct replacement for services
- Health checks - Verify new versions are healthy before switching traffic
- Proxy configuration - Update reverse proxy routing
Example Output
❯ iop
Using Git SHA for release ID: a1b2c3d
Starting deployment with release a1b2c3d
[✓] Configuration loaded (0ms)
[✓] Git status verified (3ms)
[✓] Infrastructure ready (1.2s)
Building Images
[✓] web → my-app/web:a1b2c3d (45.2s)
Deploying to Servers
└─ server1.com
├─ [✓] Loading image (3.2s)
├─ [✓] Zero-downtime deployment (2.8s)
└─ [✓] Configuring proxy (0.8s)
[✓] Deployment completed successfully in 52.1s
Your apps are live at:
└─ https://myapp.com (web)
Notes
- Infrastructure setup is automatic (no separate setup command needed)
- Commit git changes before deploying
- Requires Docker running locally for image builds
- App/service names cannot be:
init
,status
,proxy
(reserved)
iop status
Check deployment status across all servers with comprehensive information.
Usage
iop status [entry-names...] [flags]
Flags
--verbose
- Show detailed status information--help
- Show help message
Examples
iop status # Check all deployments
iop status web # Check specific app
iop status --verbose # Detailed status info
Example Output
❯ iop status
📱 App: web
Status: ✅ RUNNING (green active)
Replicas: 1/1 running
Image: my-app/web:a1b2c3d
Servers: server1.com
Last Deployed: 2 hours ago
Uptime: 2h 15m
Resource Usage: CPU 2.3%, Memory 125MB
🔧 Service: postgres
Status: ✅ RUNNING
Image: postgres:17
Servers: server1.com
Uptime: 1d 5h
Resource Usage: CPU 0.8%, Memory 95MB
🔧 Proxy Status:
server1.com: ✅ RUNNING (port 80, 443)
- Version: elitan/iop-proxy:latest
- Uptime: 1d 5h
- Active routes: 2
Status Information
For each app/service, status shows:
- Status - Current state (RUNNING, STOPPED, MIXED, UNKNOWN)
- Active color - Which deployment slot is active (blue/green) for apps
- Replicas - Number of running/desired replicas
- Image - Current deployed image
- Servers - Which servers are hosting the deployment
- Last deployed - When the deployment occurred
- Uptime - How long containers have been running
- Resource usage - CPU and memory consumption
Detailed Status (--verbose
)
With --verbose
, you get additional information:
- Exact image digests
- Container restart counts
- Exit codes (if applicable)
- Port mappings
- Volume mounts
- Container health check details
iop proxy
Manage the iop reverse proxy that handles SSL and routing.
Usage
iop proxy <subcommand> [flags]
Subcommands
status
- Show proxy status on all servers (default)update
- Update proxy to latest version on all serversdelete-host
- Remove a host from proxy configurationlogs
- Show proxy logs from all servers
Flags
--verbose
- Show detailed output--host <host>
- Target specific host (for delete-host)--lines <n>
- Number of log lines to show (for logs, default: 50)
Examples
iop proxy status # Check status on all servers
iop proxy update --verbose # Update proxy with details
iop proxy delete-host --host api.example.com # Remove specific host
iop proxy logs --lines 100 # Show last 100 log lines
iop proxy status
Shows the status of the iop proxy on all configured servers:
❯ iop proxy status
Proxy Statuses (2):
server1.com: ✅ RUNNING
- Container: iop-proxy
- Ports: 80, 443, 8080
- Image: elitan/iop-proxy:latest
- Uptime: 1d 5h
- Routes: 3 active
server2.com: ✅ RUNNING
- Container: iop-proxy
- Ports: 80, 443, 8080
- Image: elitan/iop-proxy:latest
- Uptime: 2h 30m
- Routes: 1 active
iop proxy update
Updates the proxy to the latest version on all servers:
❯ iop proxy update
server1.com
├─ [✓] Checking for updates
├─ [✓] Pulling latest image
├─ [✓] Updating proxy container
└─ [✓] Proxy updated successfully
Update Summary:
Updated: 1 server(s)
Skipped: 0 server(s) (already up to date)
iop proxy delete-host
Removes a specific host from the proxy configuration:
❯ iop proxy delete-host --host api.example.com
server1.com
└─ [✓] Host api.example.com deleted successfully
Deletion Summary:
Deleted: 1 server(s)
Not found: 0 server(s)
iop proxy logs
Shows recent logs from the proxy:
❯ iop proxy logs --lines 50
=== Proxy Logs from server1.com ===
2024-01-15 10:30:45 [INFO] Proxy server started on :80 and :443
2024-01-15 10:30:45 [INFO] API server started on :8080
2024-01-15 10:31:02 [INFO] Certificate obtained for myapp.com
2024-01-15 10:31:02 [INFO] Route configured: myapp.com -> localhost:3000
=== End logs from server1.com ===
Global Flags
These flags work with most commands:
--verbose
Show detailed output including:
- SSH connection details
- Docker command execution
- Build progress
- Deployment steps
- Error diagnostics
iop --verbose
iop status --verbose
iop proxy status --verbose
--help
Show help information for any command:
iop --help # Global help
iop init --help # Command-specific help
iop proxy status --help # Subcommand help
Exit Codes
iop commands return standard exit codes:
- 0 - Success
- 1 - General error (configuration, network, deployment failure, etc.)
This makes iop suitable for use in CI/CD pipelines:
#!/bin/bash
iop
if [ $? -eq 0 ]; then
echo "✅ Deployment successful"
else
echo "❌ Deployment failed"
exit 1
fi
Error Handling and Suggestions
iop provides helpful error messages with specific suggestions:
Configuration Errors
Error: Could not find iop.yml file
Suggestion:
Run 'iop init' to create configuration files
SSH Connection Errors
Error: SSH connection failed to server.com
Suggestions:
- Check server hostname in iop.yml
- Verify SSH access to your servers
- Use --verbose flag for detailed connection info
Docker Errors
Error: Docker build failed
Suggestions:
- Ensure Docker is running locally
- Check your Dockerfile syntax
- Use --verbose flag for detailed build output
Git Status Errors
Error: Git working directory is not clean
Suggestions:
- Commit your changes: git add . && git commit -m 'message'
For more help, use iop --help
or iop <command> --help
for command-specific information.