# How to Use holaOS for Debugging: A Complete Guide to the Debug CLI

> Master holaOS debugging with the read-only debug CLI. Inspect SQLite runtime.db to troubleshoot agent sessions, cronjobs, and workspace state safely. Get our complete guide.

- Repository: [holaboss.ai/holaOS](https://github.com/holaboss-ai/holaOS)
- Tags: how-to-guide
- Published: 2026-08-15

---

**The holaOS debug CLI is a read-only Node.js tool that inspects the SQLite `runtime.db` database to troubleshoot agent sessions, cronjobs, and workspace state without affecting production systems.**

Debugging distributed agent systems requires deep visibility into internal runtime state without disrupting live operations. The `holaboss-ai/holaOS` repository provides a dedicated debug CLI that connects directly to the SQLite state store, enabling developers to diagnose issues across workspaces, sessions, and job queues using safe, read-only queries. This guide explains how to use holaOS for debugging by leveraging the built-in commands and source architecture.

## What Is the holaOS Debug CLI?

The **debug CLI** (`holaboss-runtime`) is a Node.js script located at [`runtime/state-store/src/debug-cli.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/debug-cli.ts) that provides direct access to the holaOS runtime state. Unlike the production API server, this tool operates in **read-only mode** (`Database(..., { readonly: true })`), ensuring that inspection commands never modify the underlying `runtime.db` or `data.db` files.

The CLI parses command-line arguments, lazily opens SQLite connections using path resolvers from [`runtime/state-store/src/store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts), and dispatches sub-commands that output structured JSON for integration with tools like `jq` and `grep`.

## Core Architecture and Source Files

Understanding the file structure helps you navigate the debugging capabilities effectively.

### debug-cli.ts (Entry Point)

The primary implementation in [`runtime/state-store/src/debug-cli.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/debug-cli.ts) contains the command dispatcher and database connection logic. It validates table names with regex patterns before executing queries and enforces row limits on dump operations to prevent memory exhaustion.

### store.ts (Path Resolution)

This module exposes **`runtimeDbPath`** and **`controlPlaneDbPath`** helpers that resolve database locations from environment variables or default `.holaboss` directory structures. When debugging, these helpers ensure you connect to the correct workspace-specific or host-level databases.

### migrations/index.ts (Schema Versioning)

Located at [`runtime/state-store/src/migrations/index.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/migrations/index.ts), this file exports the `RUNTIME_DB_MIGRATIONS` catalog. The CLI compares this against the database's `user_version` pragma to determine pending schema upgrades.

### Runtime Harnesses (Data Producers)

The `runtime/harnesses/` directory contains the agent systems that populate tables like `agent_sessions`, `cronjobs`, and `session_runtime_state`. The CLI queries these tables to surface runtime behavior without instrumenting the harness code itself.

## Installing and Running the Debug CLI

The debug CLI runs directly from the repository source using `tsx`, requiring no separate installation.

```bash

# From the repository root

npx tsx runtime/state-store/src/debug-cli.ts [command] [options]

```

Ensure your environment can locate the `.holaboss` folder, which contains the SQLite databases. The CLI automatically discovers paths using the resolution logic in [`store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/store.ts).

## Essential Debug Commands

All commands output JSON for programmatic analysis. Below are the critical operations for troubleshooting holaOS deployments.

### Check System Health

Verify database connectivity and schema integrity before investigating specific issues.

```bash
npx tsx runtime/state-store/src/debug-cli.ts health

```

**Example output:**

```json
{
  "ok": true,
  "dbPath": "/path/to/host-state.db",
  "userVersion": 45,
  "tableCount": 28,
  "errors": []
}

```

The command reads the `user_version` pragma and counts tables in `sqlite_master` to confirm the runtime is reachable and properly migrated.

### List Database Tables

Enumerate all tables with row counts to identify data volume inconsistencies.

```bash
npx tsx runtime/state-store/src/debug-cli.ts tables

```

**Example output:**

```json
[
  { "table": "workspaces", "rows": 4 },
  { "table": "agent_sessions", "rows": 12 },
  { "table": "cronjobs", "rows": 3 }
]

```

The implementation iterates over `sqlite_master`, executes `SELECT COUNT(*)` for each table, and gracefully handles virtual tables that may require extensions.

### Dump Table Data

Export specific table contents for offline analysis or filtering.

```bash
npx tsx runtime/state-store/src/debug-cli.ts dump cronjobs --limit 5

```

**Example output:**

```json
[
  {
    "id": "c1",
    "enabled": 1,
    "schedule": "0 * * * *",
    "last_run": null
  }
]

```

The `dump` command validates table names against a whitelist regex, constructs safe parameterized SELECT statements, and enforces the `--limit` constraint to protect system resources.

### Inspect Workspace Sessions

Analyze agent session lifecycle and runtime status for specific workspaces.

```bash
npx tsx runtime/state-store/src/debug-cli.ts sessions my-workspace-id

```

**Example output:**

```json
[
  {
    "session_id": "s42",
    "kind": "agent",
    "title": "Chat with LLM",
    "runtime_status": "running",
    "heartbeat_at": "2026-08-15T12:34:56Z"
  }
]

```

This command resolves the workspace's filesystem path, opens the per-workspace `runtime.db`, and performs a join between `session_runtime_state` and persisted session metadata to provide a complete operational picture.

### Monitor Job Queues

Snapshot asynchronous job processing across the system.

```bash
npx tsx runtime/state-store/src/debug-cli.ts jobs

```

**Example output:**

```json
{
  "queue": [
    { "status": "ready", "count": 7 },
    { "status": "running", "count": 2 }
  ],
  "cron": [
    { "enabled": 1, "count": 3 }
  ],
  "post_run": [
    { "status": "completed", "count": 4 }
  ]
}

```

The command aggregates counts from both the root `data.db` (single-tenant layout) and legacy `runtime.db` files, deduplicating workspaces that have been consolidated to prevent double-counting.

### Verify Schema Migrations

Identify pending database migrations before upgrading holaOS versions.

```bash
npx tsx runtime/state-store/src/debug-cli.ts migrations

```

**Example output:**

```json
{
  "current": 41,
  "target": 45,
  "seedVersion": 45,
  "pending": [
    { "id": 42, "name": "Add new cronjobs table" },
    { "id": 43, "name": "Rename workspace_plugins" }
  ],
  "registered": [
    { "id": 1, "name": "Initial schema" }
  ]
}

```

By comparing `user_version` against the `RUNTIME_DB_MIGRATIONS` array, the CLI reports exactly which schema upgrades are required for compatibility.

## Safety Features and Read-Only Guarantees

The debug CLI enforces **read-only access** at the database connection level. In [`debug-cli.ts`](https://github.com/holaboss-ai/holaOS/blob/main/debug-cli.ts), the SQLite client initializes with the `readonly: true` flag, preventing accidental `INSERT`, `UPDATE`, or `DELETE` operations. This architectural decision allows developers to run debugging commands on live production databases without risk of data corruption or performance degradation from write locks.

## Summary

- The holaOS debug CLI provides **read-only inspection** of the SQLite runtime state via [`runtime/state-store/src/debug-cli.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/debug-cli.ts).
- **Six primary commands** (`health`, `tables`, `dump`, `sessions`, `jobs`, `migrations`) cover system verification, data enumeration, and schema management.
- The tool aggregates data from both **root `data.db`** and **workspace-specific `runtime.db`** files for complete visibility.
- All output is **structured JSON** for integration with standard Unix text processing tools.
- **Path resolution** automatically handles environment-specific database locations through [`store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/store.ts) helpers.

## Frequently Asked Questions

### Is the holaOS debug CLI safe to run on a live production system?

Yes. The CLI explicitly opens database connections in read-only mode using the `readonly: true` parameter in the better-sqlite3 constructor. This prevents any write operations, ensuring that inspection queries do not interfere with production API servers or agent execution.

### How does the CLI locate the SQLite database files?

The CLI uses resolution helpers defined in [`runtime/state-store/src/store.ts`](https://github.com/holaboss-ai/holaOS/blob/main/runtime/state-store/src/store.ts), specifically `runtimeDbPath` and `controlPlaneDbPath`. These functions check environment variables first, then fall back to default paths within the `.holaboss` directory structure, ensuring correct database discovery across different deployment configurations.

### Can I modify data using the debug CLI?

No. The debug CLI is intentionally designed as a read-only diagnostic tool. While it can display data from tables like `agent_sessions` and `cronjobs`, it cannot execute modifications. For data changes, you must use the production API or direct database access outside the CLI context.

### What should I do if the health check returns errors?

If the `health` command reports `ok: false` or lists errors, first verify that the database files exist at the paths reported in `dbPath` and that the executing user has read permissions. Next, run the `migrations` command to check if the database schema version matches the expected `target` version; pending migrations may indicate an incomplete deployment or version mismatch.