How to Manage the ODS Stack Using the `ods-cli`: Command Reference Guide

The ods-cli is a Bash-based command-line interface that serves as the primary entry point for installing, configuring, and maintaining the ODS (Open‑Source Distributed Stack) on your local machine.

The Osmantic/ODS repository provides this dedicated CLI to simplify orchestration of complex distributed services. When you manage the ODS stack using the ods-cli, you interact with a thin wrapper that sets environment variables, validates hardware compatibility, and delegates execution to specialized installer scripts.

Architecture of the ods-cli

The ods-cli script located at ods/ods-cli functions as a command parser and orchestration layer. It defines core command functions including cmd_start, cmd_stop, cmd_status, cmd_enable, and cmd_update, which handle user input and prepare the execution environment.

Before delegating work, the CLI establishes critical environment variables such as ODS_HOME and ODS_MODE. It then invokes ods/install-core.sh to run sequential installer phases including pre-flight checks, downloads, and compose file resolution. The heavy lifting is performed by pure-function libraries in installers/lib/*, keeping the CLI itself lean and testable.

Starting and Stopping the Stack

Initialize Services

To bring up the complete stack for the first time or after a shutdown:

bash ods/ods-cli start

This command executes several orchestrated steps. First, it runs the pre-flight phase to detect your GPU backend and validate Docker availability. Then it calls scripts/resolve-compose-stack.sh to merge the base docker-compose.base.yml with the appropriate GPU-specific overlay—such as docker-compose.nvidia.yml, docker-compose.amd.yml, or docker-compose.apple.yml—based on hardware detection. Finally, scripts/generate-runtime-config.sh writes the final .env and docker-compose.override.yml to $ODS_HOME before invoking Docker Compose to start services.

Graceful Shutdown

To stop all services and clean up resources:

bash ods/ods-cli stop

The CLI executes docker compose down --remove-orphans on the merged compose stack. It removes temporary PID files and runtime directories while preserving your persisted .env configuration for subsequent restarts.

Monitoring and Managing Services

Check System Status

For a consolidated view of service health:

bash ods/ods-cli status

The CLI queries health endpoints defined in each extension's manifest.yaml under extensions/services/*/. It returns a formatted table indicating whether each service is Running, Failed, or Disabled, ordered by SERVICE_IDS.

Enable or Disable Extensions

To activate optional services like Text-to-Speech:

bash ods/ods-cli enable tts

To deactivate:

bash ods/ods-cli disable tts

Before enabling, the CLI inspects the target extension's manifest.yaml to verify GPU backend compatibility. If compatible, it copies the extension's compose.yaml fragment into the active stack and triggers generate-runtime-config.sh to update the runtime configuration. Changes take effect after a restart.

List Available Components

To enumerate presets and extensions programmatically:

bash ods/ods-cli list --json

This traverses $ODS_HOME/presets and extensions/services/*, emitting a JSON object containing preset metadata and a map of extension IDs to their enabled states.

Maintenance Operations

Update the Stack

To pull newer images and apply configuration changes safely:

bash ods/ods-cli update

Before modifying anything, the CLI invokes ods-update.sh to create a snapshot backup for rollback safety. It then runs docker compose pull for all services and restarts the stack with refreshed images.

Backup and Restore

Create a snapshot of your current configuration:

bash ods/ods-cli backup my-backup-2024-08-30.tar.gz

Restore from a previous state:

bash ods/ods-cli restore my-backup-2024-08-30.tar.gz

The ods-backup.sh script archives the $ODS_HOME directory including service versions and environment settings. The ods-restore.sh counterpart extracts the archive, reapplies saved configurations, and restarts services automatically.

Automated Health Verification

For CI/CD pipelines or automated monitoring:

bash ods/ods-cli health-check

This executes scripts/health-check.sh in parallel against every service. It returns a non-zero exit code if any service reports unhealthy, enabling integration with automated testing workflows.

Core Implementation Files

Understanding the source structure helps troubleshoot issues when you manage the ODS stack using the ods-cli:

• ods/ods-cli – Main entry point containing command parsers and environment initialization.
• ods/install-core.sh – Orchestrates installer phases; invoked by the CLI for start, update, and related operations.
• ods/scripts/resolve-compose-stack.sh – Merges base compose files with GPU overlays and enabled extensions.
• ods/docker-compose.base.yml – Defines core services including the dashboard, API, and LLM servers.
• ods/extensions/services/**/manifest.yaml – Declares per-service metadata including ports, health endpoints, and GPU requirements.
• ods/ods-update.sh and ods/ods-backup.sh – Implement safe-update snapshots and backup creation logic.
• ods/tests/ – Comprehensive Bash test suite covering CLI syntax and edge-case behavior.

Summary

• The ods-cli in ods/ods-cli serves as the primary interface for ODS stack management, parsing commands and delegating to specialized scripts.
• Environment setup is handled automatically, with the CLI detecting GPU backends and setting variables like ODS_HOME before execution.
• Service lifecycle commands include start, stop, status, and health-check, providing full control over containerized services.
• Extension management uses enable and disable sub-commands that validate GPU compatibility against manifest.yaml files.
• Maintenance workflows such as update, backup, and restore leverage ods-update.sh and ods-backup.sh to ensure safe, reversible operations.

Frequently Asked Questions

What is the difference between ods-cli and install-core.sh?

The ods-cli is the user-facing command interface that parses arguments and sets environment variables. It delegates the actual installation logic to install-core.sh, which loads pure-function libraries from installers/lib/* and executes sequential phases. According to the Osmantic/ODS source code, this separation keeps the CLI simple while isolating complex orchestration logic in the installer.

How does ods-cli handle different GPU backends?

The CLI automatically detects available hardware during the pre-flight phase and selects the appropriate compose overlay. It stores this configuration in environment variables and calls scripts/resolve-compose-stack.sh to merge docker-compose.base.yml with the relevant GPU-specific file—such as docker-compose.nvidia.yml for NVIDIA GPUs or docker-compose.amd.yml for AMD hardware.

Can I use ods-cli in automated CI/CD pipelines?

Yes. The ods-cli health-check command is designed for automation, returning non-zero exit codes when services fail health checks defined in their manifest.yaml files. Additionally, all commands support JSON output via flags like --json, making them suitable for scripted interactions and infrastructure-as-code workflows.

Where does ods-cli store configuration and state files?

The CLI uses the ODS_HOME environment variable to determine the working directory, defaulting to the repository root. It generates .env and docker-compose.override.yml in this location via scripts/generate-runtime-config.sh. Backup archives created with ods-cli backup preserve this entire directory structure, ensuring complete state recovery during restore operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}