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

> Master ODS stack management with the ods-cli command reference guide. Install, configure, and maintain your Open-Source Distributed Stack effortlessly. Get started today.

- Repository: [Osmantic/ODS](https://github.com/Osmantic/ODS)
- Tags: command-reference
- Published: 2026-08-30

---

**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`](https://github.com/Osmantic/ODS/blob/main/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
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`](https://github.com/Osmantic/ODS/blob/main/scripts/resolve-compose-stack.sh) to merge the base [`docker-compose.base.yml`](https://github.com/Osmantic/ODS/blob/main/docker-compose.base.yml) with the appropriate GPU-specific overlay—such as [`docker-compose.nvidia.yml`](https://github.com/Osmantic/ODS/blob/main/docker-compose.nvidia.yml), [`docker-compose.amd.yml`](https://github.com/Osmantic/ODS/blob/main/docker-compose.amd.yml), or [`docker-compose.apple.yml`](https://github.com/Osmantic/ODS/blob/main/docker-compose.apple.yml)—based on hardware detection. Finally, [`scripts/generate-runtime-config.sh`](https://github.com/Osmantic/ODS/blob/main/scripts/generate-runtime-config.sh) writes the final `.env` and [`docker-compose.override.yml`](https://github.com/Osmantic/ODS/blob/main/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
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
bash ods/ods-cli status

```

The CLI queries health endpoints defined in each extension's [`manifest.yaml`](https://github.com/Osmantic/ODS/blob/main/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
bash ods/ods-cli enable tts

```

To deactivate:

```bash
bash ods/ods-cli disable tts

```

Before enabling, the CLI inspects the target extension's [`manifest.yaml`](https://github.com/Osmantic/ODS/blob/main/manifest.yaml) to verify GPU backend compatibility. If compatible, it copies the extension's [`compose.yaml`](https://github.com/Osmantic/ODS/blob/main/compose.yaml) fragment into the active stack and triggers [`generate-runtime-config.sh`](https://github.com/Osmantic/ODS/blob/main/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
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
bash ods/ods-cli update

```

Before modifying anything, the CLI invokes [`ods-update.sh`](https://github.com/Osmantic/ODS/blob/main/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
bash ods/ods-cli backup my-backup-2024-08-30.tar.gz

```

Restore from a previous state:

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

```

The [`ods-backup.sh`](https://github.com/Osmantic/ODS/blob/main/ods-backup.sh) script archives the `$ODS_HOME` directory including service versions and environment settings. The [`ods-restore.sh`](https://github.com/Osmantic/ODS/blob/main/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
bash ods/ods-cli health-check

```

This executes [`scripts/health-check.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/ods/install-core.sh)** – Orchestrates installer phases; invoked by the CLI for `start`, `update`, and related operations.
- **[`ods/scripts/resolve-compose-stack.sh`](https://github.com/Osmantic/ODS/blob/main/ods/scripts/resolve-compose-stack.sh)** – Merges base compose files with GPU overlays and enabled extensions.
- **[`ods/docker-compose.base.yml`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/ods/ods-update.sh)** and **[`ods/ods-backup.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/manifest.yaml) files.
- **Maintenance workflows** such as `update`, `backup`, and `restore` leverage [`ods-update.sh`](https://github.com/Osmantic/ODS/blob/main/ods-update.sh) and [`ods-backup.sh`](https://github.com/Osmantic/ODS/blob/main/ods-backup.sh) to ensure safe, reversible operations.

## Frequently Asked Questions

### What is the difference between `ods-cli` and [`install-core.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/scripts/resolve-compose-stack.sh) to merge [`docker-compose.base.yml`](https://github.com/Osmantic/ODS/blob/main/docker-compose.base.yml) with the relevant GPU-specific file—such as [`docker-compose.nvidia.yml`](https://github.com/Osmantic/ODS/blob/main/docker-compose.nvidia.yml) for NVIDIA GPUs or [`docker-compose.amd.yml`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/docker-compose.override.yml) in this location via [`scripts/generate-runtime-config.sh`](https://github.com/Osmantic/ODS/blob/main/scripts/generate-runtime-config.sh). Backup archives created with `ods-cli backup` preserve this entire directory structure, ensuring complete state recovery during restore operations.