Diagnostics

km status

The primary diagnostic command:

km status

This shows:

• Total items in your collection
• Breakdown by source (manual, chrome, github, etc.)
• Number of items pending enrichment
• Number of failed fetches

Checking Service Health

If you're running the background service:

km service status

Shows whether the launchd agent is running, uptime, and the PID.

km service logs

Shows recent output from the background service, including any errors during connector polling or background tasks.

REST API Health Check

The health endpoint provides machine-readable diagnostics:

curl http://localhost:3749/api/health

Returns:

{
  "status": "ok",
  "uptime": 3600,
  "collection_size": 1234,
  "last_sync": "2025-03-10T14:30:00Z"
}

Connector Health

Check the status of all configured connectors:

km connector list

Each connector shows:

• Health status — ok, error, or warning
• Last sync — When it last successfully synced
• Item count — How many items it has imported
• Schedule — Polling interval (if set)

Database Location

Find where your data is stored:

python -c "from knowmarks.config import DATA_DIR; print(DATA_DIR)"

The database file is knowmarks.db in that directory. You can inspect it directly with any SQLite client.

Log Level

Increase verbosity for debugging:

KM_LOG_LEVEL=DEBUG km serve

Debug logging shows:

• Every database query
• Embedding operations
• HTTP requests for content extraction
• LLM API calls and responses
• Connector sync details

Sharing Diagnostics in Bug Reports

When filing a bug report, include:

1. km status output
2. Python version: python --version
3. OS: macOS / Linux / Windows and version
4. Install method: pip, uv, Docker
5. Embedding provider: fastembed, Ollama, or API
6. Error output: Full terminal output with KM_LOG_LEVEL=DEBUG