CLI Commands

Reference for the end-user adhdev command-line tool.

Global Commands

`adhdev`

Show help and available commands.

`adhdev setup`

Interactive setup wizard. Authenticates your machine with ADHDev Cloud.

bash

adhdev setup
# Opens browser for device authentication
# Stores token in ~/.adhdev/config.json

`adhdev daemon`

Start the daemon process. Connects to your IDE(s) and the ADHDev server.

bash

adhdev daemon
# Runs in foreground, press Ctrl+C to stop

If you want the local-only standalone server, use the self-hosted docs instead:

`adhdev standalone`

Start the self-hosted standalone server: local dashboard + embedded daemon + standalone session-host namespace.

bash

adhdev standalone
adhdev standalone --host 0.0.0.0
adhdev standalone --port 8080
adhdev standalone --token mysecret
adhdev standalone --no-open
adhdev standalone --dev

Use this when you explicitly want the self-hosted/local-only path instead of the cloud-connected daemon flow.

Important behavior:

standalone stays localhost-only by default unless you pass --host
if you expose it on 0.0.0.0 without token auth or a dashboard password, standalone warns that the dashboard is open to your LAN
standalone uses its own session-host namespace by default so it does not fight the cloud-connected daemon for hosted runtimes on the same machine

For deeper self-hosted details, see:

`adhdev daemon:status`

Show current daemon status and local health information.

bash

adhdev daemon:status
adhdev daemon:status --port 19222

This command reports:

daemon PID and log path
local IPC reachability
session-host status when available
direct fallback status when daemon IPC is unavailable

`adhdev status`

Show current machine setup status.

bash

adhdev status

Use this when you want a quick answer to "is this machine configured and logged in?" rather than daemon/runtime diagnostics.

`adhdev mcp`

Start the ADHDev MCP server over stdio so MCP clients such as Claude Desktop can inspect and control ADHDev sessions.

bash

# Local mode: talks to the standalone daemon on localhost:3847
adhdev mcp
adhdev mcp --port 4000
adhdev mcp --password my-standalone-password

# Mesh mode: coordinator-scoped tools via daemon IPC
adhdev mcp --mode ipc --repo-mesh mesh_abc123

# Delegated-worker mode (daemon-launched, minimal toolset)
adhdev mcp --mode ipc --worker

Claude Desktop-style config:

json

{
  "mcpServers": {
    "adhdev": {
      "command": "adhdev",
      "args": ["mcp"]
    }
  }
}

Available tools (local/mesh mode): list_daemons, list_sessions, launch_session, stop_session, check_pending, read_chat, read_chat_debug, send_chat, approve, git_status, git_log, git_diff, git_checkpoint, git_push, screenshot. Mesh mode (--repo-mesh) additionally exposes a coordinator-scoped mesh_* tool set. --worker mode exposes only the minimal toolset a delegated worker needs.

Options:

Flag	Description
`--mode <mode>`	MCP transport mode: `local` or `ipc`
`--repo-mesh <mesh_id>`	Start in mesh mode (coordinator-scoped tools)
`--worker`	Delegated-worker mode — expose only the minimal worker toolset
`--port <n>`	Standalone daemon port for local mode (default: `3847`)
`--password <pass>`	Standalone daemon password/token if configured

Launch Commands

`adhdev launch [target]`

Launch or relaunch an IDE with CDP enabled, or start a CLI agent through the running daemon.

For CLI providers, a normal launch is a fresh session by default. Resume/recovery should only happen when you explicitly choose a saved session or use hosted runtime recovery on purpose.

bash

# IDEs
adhdev launch cursor          # Launch Cursor (CDP port 9333)
adhdev launch antigravity     # Launch Antigravity (CDP port 9335)
adhdev launch windsurf        # Launch Windsurf (CDP port 9336)
adhdev launch vscode          # Launch VS Code
adhdev launch kiro            # Launch Kiro

# CLI Agents (8 built-in)
adhdev daemon                 # Start the daemon once
adhdev launch claude          # Launch Claude Code session
adhdev launch codex-cli       # Launch Codex CLI session
adhdev launch cursor-cli      # Launch Cursor CLI session
adhdev launch opencode        # Launch OpenCode CLI session
adhdev launch antigravity-cli # Launch Antigravity CLI session
adhdev launch grok-cli        # Launch Grok CLI session
adhdev launch hermes-cli      # Launch Hermes session
adhdev launch kimi            # Launch Kimi session

# ACP Agents (stdio, Agent Client Protocol)
adhdev launch github-copilot  # Launch GitHub Copilot session
adhdev launch goose           # Launch Goose session

Options:

Flag	Description
`-w, --workspace <path>`	Open specific workspace/folder
`-n, --new-window`	Open in a new window
`-d, --dir <path>`	Working directory for a CLI agent (distinct from `-w`; defaults to the current directory)

WARNING

adhdev launch for IDEs will close the existing IDE process and reopen it with CDP enabled. Save your work first.

History Commands

`adhdev history list <provider>`

List saved provider-native CLI/ACP history for a provider.

bash

adhdev history list claude
adhdev history list hermes-cli --json
adhdev history list codex-cli --limit 10 --offset 10
adhdev history list claude --resumable
adhdev history list claude --sort oldest
adhdev history list claude --sort messages
adhdev history list claude --text "reply with exactly" --workspace remote_vs --model gpt-5.4

Use this first when your real goal is:

"what conversations can I continue?"
"which provider history has the context I want?"
"which saved session still has a resumable workspace?"

This command reads saved history metadata (providerSessionId, workspace, preview, message count) rather than session-host runtime records.

Useful filters and sort modes:

--resumable → show only entries that can resume immediately without needing --dir
--text <text> → filter by title or preview substring
--workspace <text> → filter by workspace path substring
--model <text> → filter by model substring
--sort recent → newest activity first (default)
--sort oldest → oldest activity first
--sort messages → highest message count first

`adhdev history resume <provider> [historySessionId]`

Resume a provider-native saved history session.

bash

adhdev history resume claude 20260414_101931_38d017
adhdev history resume hermes-cli 20260413_163128_d61494
adhdev history resume claude --dir /path/to/worktree   # choose interactively when omitted
adhdev history resume claude --resumable --sort messages
adhdev history resume claude --text "sonnet follow-up" --workspace remote_vs --model gpt-5.4

This is the primary continuity path for normal CLI use. If you want to keep talking in the same provider conversation, prefer this over runtime attach/recover. If you omit historySessionId, ADHDev will:

auto-select the only resumable saved history entry, or
open an interactive picker when multiple resumable entries exist.

Interactive picker controls:

--resumable → hide entries that still need --dir
--text <text> → filter by title or preview substring
--workspace <text> → filter by workspace path substring
--model <text> → filter by model substring
--sort recent|oldest|messages → use the same ordering semantics as history list

If the saved entry is missing workspace metadata, pass --dir explicitly.

Runtime Commands

`adhdev runtime list`

List hosted runtime recovery and diagnostics state using live/recovery/inactive groups instead of raw session-host diagnostics.

bash

adhdev runtime list
adhdev runtime list --all
adhdev runtime list --json

By default this groups records into:

live runtimes
recovery snapshots
inactive records when --all is requested

Use this first when you want to answer:

"what is actually live right now?"
"what can I recover?"
"which record is just a stale snapshot?"

`adhdev runtime attach <runtimeTarget>`

Attach your current terminal directly to a live hosted runtime.

bash

adhdev runtime attach <runtimeTarget>
adhdev runtime attach <runtimeTarget> --read-only
adhdev runtime attach <runtimeTarget> --takeover

This command only accepts live runtimes. If the target is a recovery snapshot or an inactive stopped record, it fails fast and tells you to recover or restart instead of pretending the target is attachable.

`adhdev runtime open <runtimeTarget>`

Open an adhmux workspace for a live hosted runtime.

bash

adhdev runtime open <runtimeTarget>
adhdev runtime open <runtimeTarget> --read-only
adhdev runtime open <runtimeTarget> --workspace review-pane
adhdev runtime open <runtimeTarget> -n review-pane   # short alias for --workspace

Use this when you explicitly want the advanced mux/pane workflow. Normal terminal attach and recovery flows should still start with adhdev runtime attach, adhdev runtime recover, or adhdev runtime restart.

`adhdev runtime recover <runtimeTarget>`

Recover or resume a hosted runtime record.

bash

adhdev runtime recover <runtimeTarget>
# alias
adhdev runtime resume <runtimeTarget>

`adhdev runtime restart <runtimeTarget>`

Restart a hosted runtime record.

bash

adhdev runtime restart <runtimeTarget>

`adhdev runtime stop <runtimeTarget>`

Stop a hosted runtime record.

bash

adhdev runtime stop <runtimeTarget>

`adhdev runtime snapshot <runtimeTarget>`

Print the latest terminal snapshot for a hosted runtime record.

bash

adhdev runtime snapshot <runtimeTarget>
adhdev runtime snapshot <runtimeTarget> --json

<runtimeTarget> can be a session ID, runtime key, display name, or a unique prefix from adhdev runtime list.

This is the hosted-runtime recovery and diagnostics surface. Use it when the runtime process itself needs recovery after interruption, not as the normal way to continue provider conversation history.

For the two most common runtime actions, there are also top-level shortcuts:

bash

adhdev attach <runtimeTarget>
adhdev recover <runtimeTarget>
adhdev resume <runtimeTarget>

These are direct shortcuts for adhdev runtime attach and adhdev runtime recover.

Session Host Commands

`adhdev daemon:session-host`

Inspect and control the local session host.

This is the advanced diagnostics and operator-control surface behind adhdev runtime .... It is intentionally de-emphasized from the primary CLI help because most users should start with the runtime surface first.

bash

# Show diagnostics snapshot
adhdev daemon:session-host

# Use a non-default daemon IPC port
adhdev daemon:session-host --port 19222

# Print raw diagnostics JSON
adhdev daemon:session-host --json

# Restart a hosted runtime
adhdev daemon:session-host --session <sessionId> --restart

# Resume a runtime
adhdev daemon:session-host --session <sessionId> --resume

# Stop a runtime
adhdev daemon:session-host --session <sessionId> --stop

# Send a signal
adhdev daemon:session-host --session <sessionId> --signal SIGINT

# Force-detach a stuck client
adhdev daemon:session-host --session <sessionId> --detach-client <clientId>

# Prune stale duplicate runtimes for the same provider session
adhdev daemon:session-host --prune-duplicates

# Force write ownership
adhdev daemon:session-host --session <sessionId> --acquire-write <clientId> --owner-type user

# Release write ownership
adhdev daemon:session-host --session <sessionId> --release-write <clientId>

Use this when hosted CLI sessions are stuck, disconnected, or need manual recovery.

Hosted runtime recovery is intentionally explicit. Ordinary daemon startup does not automatically re-open hosted CLI sessions unless you opt into that behavior yourself.

Options:

Flag	Description
`-p, --port <port>`	Local daemon IPC port
`--json`	Print JSON output
`--limit <count>`	Number of recent diagnostics entries to include
`--session <sessionId>`	Target runtime session
`--restart`	Restart the target runtime
`--resume`	Resume the target runtime
`--stop`	Stop the target runtime
`--signal <signal>`	Send a signal such as `SIGINT` or `SIGTERM`
`--detach-client <clientId>`	Force-detach a specific attached client
`--prune-duplicates`	Remove stale duplicate hosted runtimes
`--acquire-write <clientId>`	Force-acquire write ownership for a client
`--release-write <clientId>`	Release write ownership for a client
`--owner-type <type>`	Owner type for `--acquire-write`: `user` or `agent`

Use this when session-host and daemon state look out of sync, when a runtime is stuck in interrupted, or when write ownership needs manual recovery.

Service Management

`adhdev service install`

bash

adhdev service install

Platform	Method
macOS	LaunchAgent plist (`~/Library/LaunchAgents/dev.adhf.daemon.plist`)
Windows	VBScript in Startup folder (hidden console window)
Linux	No built-in auto-install helper

The daemon restarts automatically if it crashes, but does not restart loop if it exits cleanly (e.g. when another instance is already running).

`adhdev service uninstall`

Remove the OS background service. A currently running daemon is not affected — stop it separately with adhdev daemon:stop.

bash

adhdev service uninstall

`adhdev service status`

Show service registration state and live daemon health (PID, uptime, memory, log sizes).

bash

adhdev service status
# ✓ Service is installed.
# ✓ Daemon running — PID 12723, uptime 2h 13m, 58 MB
# Logs: stdout 4.2 KB, stderr 0 B

`adhdev service logs`

View daemon service logs in real-time (tail -f).

bash

adhdev service logs             # Follow stdout log
adhdev service logs --err       # Follow stderr log
adhdev service logs -n 50       # Show last 50 lines
adhdev service logs --clear     # Truncate all log files

`adhdev service restart`

Restart the daemon via the OS service. Sends SIGTERM to the current process and lets the service manager (launchd / Windows startup) relaunch it. Also rotates logs over 10 MB.

bash

adhdev service restart

Account & Data

`adhdev logout`

Log out from ADHDev. Clears auth credentials but keeps IDE and workspace settings.

bash

adhdev logout
adhdev logout -f   # Skip confirmation prompt

`adhdev reset`

Reset ADHDev configuration. Prompts for confirmation before clearing ~/.adhdev/config.json.

bash

adhdev reset

`adhdev uninstall`

Completely remove ADHDev from the system. Stops the daemon, removes the OS background service, and deletes all data in ~/.adhdev.

bash

adhdev uninstall
adhdev uninstall -f   # Skip confirmation prompt
adhdev uninstall --dry-run   # Print what would be deleted without deleting anything

This command performs the following steps:

Stops the running daemon process (if any)
Removes the OS background service (LaunchAgent / Startup script)
Deletes ~/.adhdev/ — all configuration, auth tokens, logs, and cached data
Prints instructions to finish with npm uninstall -g adhdev

WARNING

This cannot be undone. All settings, credentials, and downloaded providers will be permanently deleted. Use adhdev logout or adhdev reset if you only want to clear auth or config.

Version & Upgrade

`adhdev --version`

Show current ADHDev version.

`adhdev update`

Upgrade ADHDev to the latest version and restart the daemon. Alias for adhdev daemon:upgrade.

bash

adhdev update
adhdev update --no-restart   # Upgrade only, skip daemon restart

Both adhdev update and adhdev daemon:upgrade also accept a --channel <channel> flag for backward compatibility with older invocations — it is deprecated and silently ignored, since the release channel is now fixed at build time.

`adhdev daemon:upgrade`

Upgrade the daemon to the latest version.

bash

adhdev daemon:upgrade
# Downloads and installs latest version

`adhdev daemon:api [mode]`

Manage server REST API relay access. Disabled by default — dashboard traffic always uses P2P/local IPC.

bash

adhdev daemon:api           # Show current status
adhdev daemon:api enable    # Allow server-side REST proxy routes
adhdev daemon:api disable   # Revoke server-side REST proxy routes

This only affects server API proxy routes. The dashboard command/data plane remains P2P-first regardless of this setting.

Quota Commands

`adhdev quota <provider>`

Show remaining plan quota for an AI coding agent. antigravity/agy, codex, grok, and kimi query the provider's own usage API live — nothing to install.

bash

adhdev quota antigravity   # alias: agy
adhdev quota codex
adhdev quota grok
adhdev quota kimi
adhdev quota claude         # requires `adhdev quota claude:install` first

Claude Code exposes usage numbers only through its statusLine hook, so reading them means occupying that slot with a wrapper. This is opt-in and never done automatically:

bash

adhdev quota claude:install     # alias: claude-install — wraps your existing statusline
adhdev quota claude:uninstall   # alias: claude-uninstall — restores your original statusline
adhdev quota claude:status      # show whether the wrapper is set up

codex and kimi have no install/uninstall/status subcommands — there's nothing to set up for a live API query.

`adhdev quota refresh [providers...]`

Ask the running daemon to re-read provider quota now, so dashboards and mesh routing see the updated numbers immediately instead of waiting for the daemon's own cache to expire.

bash

adhdev quota refresh              # refresh all providers
adhdev quota refresh codex kimi   # refresh specific providers

A provider currently in its own HTTP 429 cooldown is not re-probed (re-hitting it would extend the throttle); it is reported with the time its cooldown lifts instead. claude and codex are local-file providers with no cooldown and always re-read.

Configuration Commands

`adhdev config env set/unset/list`

Persist a daemon-scoped env/feature-flag override that survives restarts and upgrades, applied on the next daemon restart (not the currently running process).

bash

adhdev config env set ADHDEV_WORKER_MCP on
adhdev config env unset ADHDEV_WORKER_MCP
adhdev config env list

This surface is for feature flags only — keys that look like secrets, tokens, or credentials are refused. An explicit process.env value always takes priority over a persisted override.

Diagnostics

`adhdev doctor`

Diagnose install health, native dependencies, CLI resolution, and folder browse access.

bash

adhdev doctor

This checks (among other things) the build track, native module loading (e.g. node-datachannel, sharp), whether the install is linked/dev or a normal npm global package, CLI binary resolution on PATH, and read access to common folder-browse roots. Use this first when something in the daemon or its native dependencies looks broken, before filing an issue.

Advanced Commands

Commands such as adhdev provider ..., adhdev cdp ..., and adhdev daemon --dev are primarily for diagnostics, provider work, or local debugging. They are intentionally left out of the normal user workflow here.

CLI Commands ​

Global Commands ​

adhdev ​

adhdev setup ​

adhdev daemon ​

adhdev standalone ​

adhdev daemon:status ​

adhdev status ​

adhdev mcp ​

Launch Commands ​

adhdev launch [target] ​

History Commands ​

adhdev history list <provider> ​

adhdev history resume <provider> [historySessionId] ​

Runtime Commands ​

adhdev runtime list ​

adhdev runtime attach <runtimeTarget> ​

adhdev runtime open <runtimeTarget> ​

adhdev runtime recover <runtimeTarget> ​

adhdev runtime restart <runtimeTarget> ​

adhdev runtime stop <runtimeTarget> ​

adhdev runtime snapshot <runtimeTarget> ​

Session Host Commands ​

adhdev daemon:session-host ​

Service Management ​

adhdev service install ​

adhdev service uninstall ​

adhdev service status ​

adhdev service logs ​

adhdev service restart ​

Account & Data ​

adhdev logout ​

adhdev reset ​

adhdev uninstall ​

Version & Upgrade ​

adhdev --version ​

adhdev update ​

adhdev daemon:upgrade ​

adhdev daemon:api [mode] ​

Quota Commands ​

adhdev quota <provider> ​

adhdev quota refresh [providers...] ​

Configuration Commands ​

adhdev config env set/unset/list ​

Diagnostics ​

adhdev doctor ​

Advanced Commands ​

CLI Commands

Global Commands

`adhdev`

`adhdev setup`

`adhdev daemon`

`adhdev standalone`

`adhdev daemon:status`

`adhdev status`

`adhdev mcp`

Launch Commands

`adhdev launch [target]`

History Commands

`adhdev history list <provider>`

`adhdev history resume <provider> [historySessionId]`

Runtime Commands

`adhdev runtime list`

`adhdev runtime attach <runtimeTarget>`

`adhdev runtime open <runtimeTarget>`

`adhdev runtime recover <runtimeTarget>`

`adhdev runtime restart <runtimeTarget>`

`adhdev runtime stop <runtimeTarget>`

`adhdev runtime snapshot <runtimeTarget>`

Session Host Commands

`adhdev daemon:session-host`

Service Management

`adhdev service install`

`adhdev service uninstall`

`adhdev service status`

`adhdev service logs`

`adhdev service restart`

Account & Data

`adhdev logout`

`adhdev reset`

`adhdev uninstall`

Version & Upgrade

`adhdev --version`

`adhdev update`

`adhdev daemon:upgrade`

`adhdev daemon:api [mode]`

Quota Commands

`adhdev quota <provider>`

`adhdev quota refresh [providers...]`

Configuration Commands

`adhdev config env set/unset/list`

Diagnostics

`adhdev doctor`

Advanced Commands