Skip to content

Komodo CLI Reference

CLI commands, connectivity, and GitOps workflow rules.

Source: extracted from AGENTS.md

Komodo CLI Quick Reference

Core version: v2.2.0 — API uses /read/*, /write/*, and /execute endpoints.

Connectivity: Use Tailscale IP directly (Cloudflare blocks POST API requests).

  • KOMODO_ADDRESS=http://100.126.172.96:9120 (Core on development server)
  • Do NOT use https://komodo.minhluc.info/ — Cloudflare returns 403 for API calls
  • Do NOT use /api/* paths — they serve the frontend HTML, not JSON

CLI: Binary km v2.2.0 installed at ~/.local/bin/km (preferred over Python script). Config file: ~/.config/komodo/komodo.cli.toml

REST API (Fallback when CLI fails)

When km returns "failed to reach Komodo API", use curl directly with the same credentials:

# Auth: two headers from ~/.config/komodo/komodo.cli.toml
#   X-API-Key: <cli_key>
#   X-API-Secret: <cli_secret>

# Deploy a stack
curl -s -X POST 'http://100.126.172.96:9120/execute' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <cli_key>" \
  -H "X-API-Secret: <cli_secret>" \
  -d '{"type":"DeployStack","params":{"stack":"<name>"}}'

# Get stack info
curl -s -X POST 'http://100.126.172.96:9120/read/GetStack' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <cli_key>" \
  -H "X-API-Secret: <cli_secret>" \
  -d '{"stack":"<name>"}'

# List all stacks
curl -s -X POST 'http://100.126.172.96:9120/read/ListStacks' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <cli_key>" \
  -H "X-API-Secret: <cli_secret>" \
  -d '{}'

# Run resource sync
curl -s -X POST 'http://100.126.172.96:9120/execute' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <cli_key>" \
  -H "X-API-Secret: <cli_secret>" \
  -d '{"type":"CommitSync","params":{"sync":"<sync-name>"}}'

API Structure

Category URL Pattern Body Format
Read POST /read/<VariantName> {"stack":"...", ...}
Write POST /write/<VariantName> Resource-specific fields
Execute POST /execute/<TypeName> OR POST /execute Path-based: {"stack":"..."} or wrapped: {"type":"DeployStack","params":{...}}

Key Gotchas

  • /api/* paths return frontend HTML — use /read/, /write/, /execute
  • Execute has two valid formats: path-based (/execute/DeployStack) or type-wrapper (/execute + {"type":"...","params":{}}). Both work.
  • Write variants are CamelCase: CreateStack, UpdateStack, DeleteStack
  • GET /write/* returns 405 — all endpoints require POST
  • Execute response includes "success":true + "status":"InProgress" — check logs separately
# Status
km list                       # List all servers, stacks, syncs
km list servers               # List servers only
km list stacks                # List stacks only

# Resource sync (trigger after git push)
# NOTE: "commit" and "run-sync" are aliases for the same RunSync endpoint
km x commit root-syncs        # Sync a specific resource sync
km x run-sync <category>      # Same operation, different alias

# Stack operations (non-interactive: pipe empty string)
echo "" | km x deploy-stack <name>    # Deploy a stack
echo "" | km x destroy-stack <name>   # Destroy a stack
echo "" | km x restart-stack <name>   # Restart a stack
echo "" | km x stop-stack <name>      # Stop a stack
echo "" | km x start-stack <name>     # Start a stack

# Logs
km-logs -S <name>          # Get stack logs

# Server stats
km server-stats <name>        # CPU, memory, disk usage

# Procedures / builds
echo "" | km x run-procedure <name>   # Run a procedure
echo "" | km x run-build <name>       # Run a build

GitOps Workflow (MANDATORY)

NEVER deploy, create, update, or delete resources via:

  • SSH + docker/docker compose commands
  • Komodo CLI deploy/execute commands directly (without git push first)
  • Komodo UI manual creation
  • Any method other than git push → deploy

ALL changes go through git, ALWAYS commit & push & deploy in one step:

1. Edit local files (compose.yaml / TOML)
2. git add + commit + push + deploy-stack

Standard one-liner (compose-only changes):

git add -A && git commit -m "chore(<stack>): <message>" && git push && echo "" | km x deploy-stack <name>

With sync (TOML changes, new stacks):

git add -A && git commit -m "chore(<stack>): <message>" && git push && echo "" | km x run-sync <category> && echo "" | km x deploy-stack <name>

Rules:

  • Compose.yaml-only changes → deploy-stack directly (no sync needed)
  • TOML changes → run-sync + deploy-stack
  • NEVER push without deploying — changes must be live before moving on
  • ALWAYS verify deploy result (SUCCESSFUL vs FAILED)
  • File ownership rule: All services on unraid MUST write files as nobody (99:100). Set user: "99:100" in compose và chown -R 99:100 volumes trong pre_deploy.