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

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 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, 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 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, 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.

# 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.

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.

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

Example output:

{
  "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.

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

Example output:

[
  { "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.

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

Example output:

[
  {
    "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.

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

Example output:

[
  {
    "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.

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

Example output:

{
  "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.

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

Example output:

{
  "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, 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.
• 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 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, 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.

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