ironclaw status

Show system health and diagnostics

Overview

The ironclaw status command displays system health information, including database connectivity, authentication status, installed tools, and configuration details.

Usage

ironclaw status

No options or arguments required.

Output

IronClaw Status
===============

  Version:     ironclaw v0.1.0
  Database:    connected (PostgreSQL)
  Session:     found (/home/user/.ironclaw/session.json)
  Secrets:     configured (env)
  Embeddings:  enabled (provider: openai, model: text-embedding-3-small)
  WASM Tools:  3 installed (/home/user/.ironclaw/tools)
  Channels:    cli, http:3000
  Heartbeat:   enabled (interval: 300s)
  MCP Servers: 2 enabled / 3 configured

  Config:      /home/user/.ironclaw/.env

Status Fields

Version

Displays the IronClaw version number:

  Version:     ironclaw v0.1.0

Database

Shows database backend and connection status:

  Database:    connected (PostgreSQL)

Possible values:

• connected (PostgreSQL) - PostgreSQL connected successfully
• libSQL (/path/to/db) - Local libSQL database
• libSQL (/path/to/db + Turso sync) - libSQL with Turso synchronization
• error (connection refused) - Connection failed
• not configured - DATABASE_URL not set

If you see an error, run ironclaw doctor for detailed diagnostics.

Session

Indicates NEAR AI authentication status:

  Session:     found (/home/user/.ironclaw/session.json)

Possible values:

• found (/path/to/session.json) - Authenticated, session file exists
• not found (run 'ironclaw onboard') - Not authenticated

If using API key mode:

  Session:     API key configured

Secrets

Shows secrets encryption key configuration:

  Secrets:     configured (env)

Possible values:

• configured (env) - Master key found in SECRETS_MASTER_KEY environment variable
• env not set (keychain may be configured) - Not in env, may be in system keychain

The status command doesn’t probe the keychain to avoid triggering password dialogs.

Embeddings

Embeddings configuration for semantic search:

  Embeddings:  enabled (provider: openai, model: text-embedding-3-small)

Possible values:

• enabled (provider: X, model: Y) - Embeddings enabled with provider and model
• disabled - Semantic search not enabled

WASM Tools

Number of installed WASM tools:

  WASM Tools:  3 installed (/home/user/.ironclaw/tools)

Possible values:

• N installed (/path/to/tools) - N tools found
• directory not found (/path/to/tools) - Tools directory doesn’t exist

Channels

Enabled communication channels:

  Channels:    cli, http:3000

Possible channels:

• cli - Command-line interface (always enabled)
• http:3000 - HTTP API on port 3000
• N wasm - N WASM channel plugins installed

Heartbeat

Heartbeat loop status:

  Heartbeat:   enabled (interval: 300s)

Possible values:

• enabled (interval: Ns) - Heartbeat enabled, runs every N seconds
• disabled - Heartbeat loop disabled

The heartbeat loop runs periodic maintenance tasks like updating HEARTBEAT.md and checking for scheduled jobs.

MCP Servers

Configured MCP servers:

  MCP Servers: 2 enabled / 3 configured

Format: N enabled / M configured

If no servers are configured:

  MCP Servers: none configured

Config

Path to the configuration file:

  Config:      /home/user/.ironclaw/.env

Examples

Quick health check

ironclaw status

Use this to quickly verify your installation is working.

Check after configuration changes

After modifying settings, verify they’re applied:

ironclaw config set heartbeat.enabled true
ironclaw status

Verify installation

After installing tools or MCP servers:

ironclaw tool install ~/my-tool
ironclaw status

You should see the tool count increase.

Troubleshooting

If the agent isn’t working:

ironclaw status
ironclaw doctor

Compare the outputs to identify issues.

Status vs Doctor

Two commands provide health information:

ironclaw status

• Quick overview of current state
• Passive checks (no network calls)
• Fast execution
• Use for routine monitoring

ironclaw doctor

• Active diagnostics with network probes
• Tests external dependencies
• Validates configuration
• Use for troubleshooting

Run status regularly to monitor your system. Run doctor when something’s wrong.

Interpreting Results

Healthy System

A healthy installation looks like:

  Version:     ironclaw v0.1.0
  Database:    connected (PostgreSQL)
  Session:     found (/home/user/.ironclaw/session.json)
  Secrets:     configured (env)
  Embeddings:  enabled (provider: openai, model: text-embedding-3-small)
  WASM Tools:  5 installed (/home/user/.ironclaw/tools)
  Channels:    cli, http:3000
  Heartbeat:   enabled (interval: 300s)
  MCP Servers: 3 enabled / 3 configured

Common Issues

Database not connected:

  Database:    error (connection refused)

→ Check DATABASE_URL or run ironclaw doctor

Session not found:

  Session:     not found (run 'ironclaw onboard')

→ Run ironclaw onboard to authenticate

No tools installed:

  WASM Tools:  0 installed (/home/user/.ironclaw/tools)

→ Install tools with ironclaw tool install <path>

MCP servers not enabled:

  MCP Servers: 0 enabled / 3 configured

→ Enable servers with ironclaw mcp toggle <name> --enable

Automation

You can parse the status output in scripts:

# Check if database is connected
if ironclaw status | grep -q "Database.*connected"; then
  echo "Database OK"
else
  echo "Database ERROR"
  exit 1
fi

Or use it in monitoring systems:

#!/bin/bash
# Healthcheck script
ironclaw status > /tmp/ironclaw-status.txt
if [ $? -eq 0 ]; then
  exit 0
else
  exit 1
fi

Related Commands

ironclaw doctor

Run comprehensive diagnostics

ironclaw config list

View all configuration settings

ironclaw service status

Check service status

ironclaw onboard

Fix configuration issues