Skip to main content

​
Usage

codaph doctor [options]
Runs diagnostic checks on Codaph configuration, Mubit connectivity, and sync automation setup. Useful for troubleshooting issues.

​
Options

​
--cwd
string
Working directory path. Defaults to current directory.
​
--mubit
boolean
Force enable Mubit for diagnostics.
​
--mubit-api-key
string
Override Mubit API key for testing.
​
--mubit-project-id
string
Override Mubit project ID.
​
--mubit-actor-id
string
Override Mubit actor ID.

​
Diagnostic Checks

The doctor command checks:

​
Environment

  • Current working directory
  • Local repository ID detection
  • Git repository status

​
Mubit Configuration

  • API key presence (environment variables and config)
  • Project ID resolution
  • Actor ID detection
  • Run scope configuration
  • Endpoint connectivity
  • Write timeout settings

​
Sync Automation

  • Automation enabled status
  • Git hook setup (post-commit, post-push)
  • Agent completion hooks
  • Auto-pull configuration
  • Remote sync state
  • Cooldown settings

​
OpenAI Integration

  • OpenAI API key presence
  • Agent mode status

​
Example Output

$ codaph doctor

cwd: /Users/dev/myproject
repoId(local): owner/myproject
Mubit project id: owner/myproject
Mubit run scope: project
Mubit actor id: developer
env MUBIT_API_KEY present: yes
flag/env key resolved: yes
Mubit requested: yes
Mubit runtime: enabled
Mubit run scope preview: codaph:owner/myproject
Mubit write timeout: 15000ms
Sync automation: enabled (post-commit:on, agent-complete:on, autoPull:on, tuiWarm:on, cooldown=300s)
Remote sync state: lastSuccess=2026-03-01T10:00:00.000Z received=156 imported=156 dedup=0 sameSnapshot=0 capped=no pending=no
OpenAI key present: no
OpenAI agent: disabled
Mubit setup looks valid from env/flags.

​
Exit Codes

  • 0 - All checks passed
  • Non-zero values indicate configuration issues (doctor always exits 0 but reports problems in output)

​
Common Issues

​
Mubit API Key Not Found

Problem: env MUBIT_API_KEY present: no Solution: Set your Mubit API key: 
export MUBIT_API_KEY=your_key_here
# or
codaph setup --mubit-api-key your_key_here

​
Mubit Runtime Disabled

Problem: Mubit runtime: disabled Possible Causes:
  1. API key not set or invalid
  2. Network connectivity issues
  3. Mubit explicitly disabled with --no-mubit
Solution: 
codaph doctor --mubit

​
Sync Automation Not Working

Problem: Sync automation: disabled Solution: Enable automation: 
codaph init --auto-sync

​
Git Hooks Not Installed

Problem: post-commit:off or agent-complete:off Solution: Reinstall hooks: 
codaph hooks run post-commit --install
codaph hooks run agent-complete --install

Build docs developers (and LLMs) love

Get started for freeTalk to us