cli-reference.md

CLI Reference

agentdesk — AI agent orchestration platform

Derived from the clap definitions in src/cli/args.rs (and the Args / Subcommand types it references). Commands are listed in declaration order, matching agentdesk --help. Running agentdesk with no subcommand starts the server.

Regenerate with python3 scripts/generate_cli_reference.py; CI fails when this file drifts.

• Top-level commands: 54
• Commands including nested subcommands: 96

Global options

Argument	Value	Default	Description
--json	flag		Emit machine-readable JSON instead of the human-readable text output. Accepted globally — before or after the subcommand. Commands that only ever emit JSON treat this as a no-op (never a double-encode). (accepted before or after the subcommand)
-h, --help	flag		Print help
-V, --version	flag		Print version

Command index

Command	Summary	Notes
agentdesk dcserver	Start Discord bot server(s)
agentdesk init	Run the initial setup wizard
agentdesk reconfigure	Re-run the configuration wizard
agentdesk emit-launchd-plist	Emit a launchd plist using the canonical Rust renderer
agentdesk restart-dcserver	Restart Discord bot server(s)
agentdesk discord-sendfile	Deprecated: send a file to a Discord channel	deprecated
agentdesk discord-sendmessage	Deprecated: send a message to a Discord channel	deprecated
agentdesk discord-senddm	Deprecated: send a direct message to a Discord user	deprecated
agentdesk send	Send a routed Discord message without HTTP server dependency
agentdesk send-to-agent	Send a trigger-capable agent handoff through the announce bot
agentdesk review-verdict	Submit a review verdict without HTTP server dependency
agentdesk review-decision	Submit a review decision without HTTP server dependency
agentdesk review-recover-target	Recover a review dispatch target commit/worktree through the API
agentdesk docs	Read API documentation without HTTP server dependency
agentdesk auto-queue	Auto-queue operations without HTTP server dependency
agentdesk auto-queue activate	Activate an auto-queue run
agentdesk auto-queue add	Add a card to an auto-queue run
agentdesk auto-queue config	Update auto-queue runtime config
agentdesk turn-lease	Inspect or explicitly release one turn lease while preserving its session
agentdesk turn-lease inspect	Read the exact active mailbox lease (JSON, no mutation)
agentdesk turn-lease release	Release that lease without stopping or restarting the provider session
agentdesk force-kill	Force-kill a session without HTTP server dependency
agentdesk github-sync	Sync GitHub issues without HTTP server dependency
agentdesk monitoring	Monitor status commands for Discord channels
agentdesk monitoring start	Register or refresh a monitor status entry
agentdesk monitoring stop	Remove a monitor status entry
agentdesk intake-outbox	intake_outbox operator tools (Phase 5 of intake-node-routing)
agentdesk intake-outbox dispatched-audit	List dispatched rows and their recorded audit facts without changing them.
agentdesk intake-outbox dispatched-settle	Settle a dispatched handoff as unknown without creating a retry child that could redeliver an already delivered turn.
agentdesk intake-outbox spawned-settle	Settle a spawned handoff as unknown without creating a retry child that could redeliver an already delivered turn.
agentdesk intake-outbox status	Show recent intake_outbox rows (newest first).
agentdesk intake-outbox force-fail	Force-fail a stuck row and re-enqueue a fresh attempt. Implements transition 12 from the design doc.
agentdesk discord	Discord utility commands without HTTP server dependency
agentdesk discord read	Read channel messages
agentdesk discord category-create	Create a guild category. Idempotent (list-then-create): returns the existing category when one with the same name is already present. Not safe under concurrent invocations against the same guild.
agentdesk discord channel-create	Create a text channel under an optional category. Idempotent by (name, parent category) via list-then-create. Not safe under concurrent invocations against the same guild.
agentdesk discord thread-create	Create a thread under a text/news channel or a post under a forum/media channel. Cross-process safe and idempotent by (parent, normalized name) across active and archived public threads.
agentdesk card	Kanban utility commands without HTTP server dependency
agentdesk card create	Create a card from a GitHub issue
agentdesk card status	Inspect a card and connected lifecycle state
agentdesk cherry-merge	Cherry-pick a worktree branch into main and optionally close its issue
agentdesk tmux-wrapper	tmux + Claude CLI integration wrapper (Unix only)	#[cfg(unix)]
agentdesk codex-tmux-wrapper	tmux + Codex CLI integration wrapper (Unix only)	#[cfg(unix)]
agentdesk qwen-tmux-wrapper	tmux + Qwen CLI integration wrapper (Unix only)	#[cfg(unix)]
agentdesk claude-hook-relay	Relay Claude Code hook stdin JSON to the AgentDesk TUI hook receiver
agentdesk codex-hook-relay	Relay Codex hook stdin JSON to the AgentDesk TUI hook receiver
agentdesk reset-tmux	Kill all AgentDesk-* tmux sessions and clean temp files
agentdesk ismcptool	Check if MCP tool(s) are registered in .claude/settings.json
agentdesk addmcptool	Add MCP tool permission(s) to .claude/settings.json
agentdesk install-memento-session-hook	#2655: install (or refresh) the Memento context() SessionStart hook and a UserPromptSubmit token-pressure reminder into a Claude Code settings file. Idempotent — running twice produces the same file.
agentdesk status	Show server health, active sessions, and auto-queue status
agentdesk cards	List kanban cards
agentdesk dispatch	Dispatch operations
agentdesk dispatch list	List active dispatches
agentdesk dispatch retry	Retry a dispatch for a card
agentdesk dispatch redispatch	Redispatch a card
agentdesk resume	Resume a stuck kanban card from its current state
agentdesk advance	Complete pending dispatch and advance to review
agentdesk queue	Show auto-queue status with thread links	deprecated
agentdesk query	Unified queue + dispatch + phase-gate inspection (issue #2651).
agentdesk query queue	Auto-queue run + entries snapshot (calls /api/queue/status).
agentdesk query dispatches	Pending dispatches across all agents (calls /api/dispatches/pending).
agentdesk query phase-gate	Phase-gate catalog + active gate state (calls /api/queue/phase-gates/catalog).
agentdesk query all	All sections in one shot (default).
agentdesk phase	Phase-gate violation snapshot (issue #2657).
agentdesk phase status	Show current violations (default).
agentdesk deploy	Build + deploy dev + promote to release
agentdesk agents	List agents and their status
agentdesk diag	Show turn/session diagnostics for an agent ID or Discord channel ID
agentdesk config	Runtime config get/set
agentdesk config get	Get current runtime config
agentdesk config set	Set runtime config (JSON string)
agentdesk config audit	Audit config source-of-truth drift across yaml/DB/legacy files
agentdesk config sync-mcp	Sync runtime MCP servers into provider config files
agentdesk api	Call any API endpoint (curl replacement)
agentdesk terminations	List session termination events
agentdesk doctor	Environment diagnostics
agentdesk migrate	Migration helpers
agentdesk migrate openclaw	Import OpenClaw durable state into AgentDesk
agentdesk release-migrate-postgres	Apply pending PostgreSQL migrations before release activation	hidden from --help
agentdesk provider-cli	Provider CLI safe migration management
agentdesk provider-cli status	Show current registry channels and migration states
agentdesk provider-cli plan	Show what a migration would do without running it
agentdesk provider-cli upgrade	[step] Snapshot current binary and run upgrade
agentdesk provider-cli smoke	[step] Run smoke checks against current or candidate binary
agentdesk provider-cli canary	[step] Select a canary agent for the migration
agentdesk provider-cli promote	Confirm promotion after canary passes (operator gate)
agentdesk provider-cli rollback	Roll back migration to previous state
agentdesk provider-cli cleanup	List paths eligible for cleanup (dry-run only — deletion not implemented)
agentdesk provider-cli run	Run full migration orchestration up to CanaryActive
agentdesk provider-cli resume	Resume migration from the current persisted state
agentdesk show	Inspect deterministic session-binding values (epic #2285 E1).
agentdesk show session-name	Print the expected tmux session name for a Discord channel.
agentdesk health	Show consolidated health snapshot of the current node (server status, dcserver pid, last deploy time, queue lag, Discord/disk/outbox).
agentdesk machine-compare	Compare release/main/dev state across every registered worker node (mac-mini, mac-book, …). Renders a side-by-side table with dcserver pid, last deploy, queue lag, and a diff column.
agentdesk activity	Time-windowed activity report: commits / closed issues / merged PRs / deploys / incidents in a single table. Uses gh + git + AgentDesk API.

Commands

agentdesk dcserver

Start Discord bot server(s)

Usage: agentdesk dcserver [TOKEN]

Argument	Value	Default	Description
[TOKEN]	String		Bot token (defaults to configured Discord bots or AGENTDESK_TOKEN env)

agentdesk init

Run the initial setup wizard

Usage: agentdesk init

agentdesk reconfigure

Re-run the configuration wizard

Usage: agentdesk reconfigure

agentdesk emit-launchd-plist

Emit a launchd plist using the canonical Rust renderer

Usage: agentdesk emit-launchd-plist [OPTIONS]

Argument	Value	Default	Description
--flavor <FLAVOR> (required)	release		Runtime flavor to render
--label <LABEL>	String		Override the launchd Label in the generated plist
--home <HOME>	PathBuf		Override the home directory used in generated paths
--root-dir <ROOT_DIR>	PathBuf		Override the runtime root directory used in generated paths
--agentdesk-bin <AGENTDESK_BIN>	PathBuf		Override the agentdesk binary path used in ProgramArguments
--output <OUTPUT>	PathBuf		Write the plist to this path instead of stdout

agentdesk restart-dcserver

Restart Discord bot server(s)

Usage: agentdesk restart-dcserver [OPTIONS]

Argument	Value	Default	Description
--report-channel-id <REPORT_CHANNEL_ID>	u64		Discord channel ID for restart completion report
--report-provider <REPORT_PROVIDER>	claude, codex, gemini, opencode, qwen		Provider for restart report (claude, codex, gemini, opencode, or qwen)
--report-message-id <REPORT_MESSAGE_ID>	u64		Existing message ID to edit for restart report

agentdesk discord-sendfile

Deprecated: send a file to a Discord channel

Notes: deprecated.

Usage: agentdesk discord-sendfile [OPTIONS] <PATH>

Argument	Value	Default	Description
<PATH>	String		File path to send
--channel <CHANNEL> (required)	u64		Discord channel ID
--key <KEY> (required)	String		Authentication key hash

Deprecated compatibility command. The routed send command does not currently accept file attachments, so keep using this command until an attachment-capable replacement is available.

agentdesk discord-sendmessage

Deprecated: send a message to a Discord channel

Notes: deprecated.

Usage: agentdesk discord-sendmessage [OPTIONS]

Argument	Value	Default	Description
--channel <CHANNEL> (required)	u64		Discord channel ID
--message <MESSAGE> (required)	String		Message text
--key <KEY>	String		Authentication key hash (optional; without it, configured bot tokens are tried sequentially until one succeeds)

Deprecated compatibility command. With --key, this command selects that one configured bot token; without --key, it tries configured bot tokens sequentially until one succeeds. For a role-mapped channel with a configured bot runtime, migrate to agentdesk send --target channel:<id> --content <TEXT>. Routed send instead requires role-map authorization and selects one --bot runtime (default: announce), so it does not preserve this command's token selection or sequential fallback. Keep using this compatibility command when those routing requirements do not match the current delivery.

agentdesk discord-senddm

Deprecated: send a direct message to a Discord user

Notes: deprecated.

Usage: agentdesk discord-senddm [OPTIONS]

Argument	Value	Default	Description
--user <USER> (required)	u64		Discord user ID
--message <MESSAGE> (required)	String		Message text
--key <KEY>	String		Authentication key hash (optional; without it, configured bot tokens are tried sequentially until one succeeds)

Deprecated compatibility command. With --key, this command selects that one configured bot token; without --key, it tries configured bot tokens sequentially until one succeeds. Routed send instead requires a role-map-authorized channel or agent target and selects one configured --bot runtime (default: announce); it does not preserve this token fallback, target a Discord user, or create a DM. Keep using this command until a supported replacement is available.

agentdesk send

Send a routed Discord message without HTTP server dependency

Usage: agentdesk send [OPTIONS]

Argument	Value	Default	Description
--target <TARGET> (required)	String		Target must be channel:, channel:, or agent:; bare channel IDs/names are accepted for compatibility.
--source <SOURCE>	String		Source label recorded in the send envelope
--bot <BOT>	String		Preferred Discord bot name
--content <CONTENT> (required)	String		Message body

agentdesk send-to-agent

Send a trigger-capable agent handoff through the announce bot

Usage: agentdesk send-to-agent [OPTIONS]

Argument	Value	Default	Description
--from <FROM_AGENT_ID> (required)	String		Source agent id recorded in the message envelope
--to <TO_AGENT_ID> (required)	String		Target agent id whose Discord channel binding is used
--message <MESSAGE> (required)	String		Message body
--channel-kind <CHANNEL_KIND>	cc, cdx	cc	Target channel binding kind
--no-prefix	flag		Send the body without the automatic handoff prefix
--expect-reply <EXPECT_REPLY> (required)	true, false		Required: true → 회신 필수, false → 회신 불필요.
--start-turn	flag		#3556 — reserve a headless turn on the target mailbox instead of posting an announce message. Authoritative wake-up: exits non-zero on 409 (mailbox busy). Mutually exclusive with the default announce-post behavior.

agentdesk review-verdict

Submit a review verdict without HTTP server dependency

Usage: agentdesk review-verdict [OPTIONS]

Argument	Value	Default	Description
--dispatch <DISPATCH_ID> (required)	String		Review dispatch ID
--verdict <VERDICT> (required)	String		Verdict: pass, improve, rework, reject, approved
--notes <NOTES>	String		Optional verdict notes
--feedback <FEEDBACK>	String		Optional detailed feedback
--provider <PROVIDER>	String		Reviewer provider id for counter-model reviews
--commit <COMMIT>	String		Reviewed commit SHA

agentdesk review-decision

Submit a review decision without HTTP server dependency

Usage: agentdesk review-decision [OPTIONS]

Argument	Value	Default	Description
--card <CARD_ID> (required)	String		Kanban card ID
--decision <DECISION> (required)	String		Decision: approve, rework, escalate, accept, dispute, dismiss, requeue, resume
--comment <COMMENT>	String		Optional decision comment
--dispatch <DISPATCH_ID>	String		Optional dispatch scope for agent reply decisions

agentdesk review-recover-target

Recover a review dispatch target commit/worktree through the API

Usage: agentdesk review-recover-target [OPTIONS]

Argument	Value	Default	Description
--dispatch <DISPATCH_ID>	String		Review dispatch ID
--card <CARD_ID>	String		Kanban card ID, used to resolve the latest review dispatch when --dispatch is omitted
--commit <TARGET_COMMIT>	String		Reviewed commit SHA to pin
--worktree <WORKTREE_PATH>	String		Worktree path whose HEAD must match the reviewed commit
--reason <REASON>	String		Operator reason stored in the audit event

agentdesk docs

Read API documentation without HTTP server dependency

Usage: agentdesk docs [OPTIONS] [CATEGORY]

Argument	Value	Default	Description
[CATEGORY]	String		Optional docs category
--flat	flag		Emit flat endpoint list

agentdesk auto-queue

Auto-queue operations without HTTP server dependency

Usage: agentdesk auto-queue <COMMAND>

Subcommands:

• activate — Activate an auto-queue run
• add — Add a card to an auto-queue run
• config — Update auto-queue runtime config

agentdesk auto-queue activate

Activate an auto-queue run

Usage: agentdesk auto-queue activate [OPTIONS]

Argument	Value	Default	Description
--run <RUN_ID>	String		Auto-queue run ID
--agent <AGENT_ID>	String		Target agent ID
--repo <REPO>	String		Repository in owner/repo form
--active-only	flag		Restrict activation to already-live entries

agentdesk auto-queue add

Add a card to an auto-queue run

Usage: agentdesk auto-queue add [OPTIONS] <CARD_ID>

Argument	Value	Default	Description
<CARD_ID>	String		Card ID or issue number
--run <RUN_ID>	String		Auto-queue run ID
--priority <PRIORITY>	i64		Explicit priority rank
--phase <PHASE>	i64		Batch phase
--thread-group <THREAD_GROUP>	i64		Thread group
--agent <AGENT_ID>	String		Agent override

agentdesk auto-queue config

Update auto-queue runtime config

Usage: agentdesk auto-queue config [OPTIONS]

Argument	Value	Default	Description
--run <RUN_ID>	String		Auto-queue run ID
--repo <REPO>	String		Repository in owner/repo form
--agent <AGENT_ID>	String		Target agent ID
--max-concurrent <MAX_CONCURRENT_THREADS> (required)	i64		Max concurrently active threads

agentdesk turn-lease

Inspect or explicitly release one turn lease while preserving its session

Usage: agentdesk turn-lease <COMMAND>

Subcommands:

• inspect — Read the exact active mailbox lease (JSON, no mutation)
• release — Release that lease without stopping or restarting the provider session

agentdesk turn-lease inspect

Read the exact active mailbox lease (JSON, no mutation)

Usage: agentdesk turn-lease inspect [OPTIONS]

Argument	Value	Default	Description
--provider <PROVIDER> (required)	String
--channel-id <CHANNEL_ID> (required)	std::num::NonZeroU64

agentdesk turn-lease release

Release that lease without stopping or restarting the provider session

Usage: agentdesk turn-lease release [OPTIONS]

Argument	Value	Default	Description
--expected <EXPECTED> (required)	String		Exact JSON object returned by inspect; never resolved from current age
--reason <REASON> (required)	String		Operator's explanation of why this turn may be released

agentdesk force-kill

Force-kill a session without HTTP server dependency

Usage: agentdesk force-kill [OPTIONS]

Argument	Value	Default	Description
--session-key <SESSION_KEY> (required)	String		Session key
--retry	flag		Requeue card after force-kill

agentdesk github-sync

Sync GitHub issues without HTTP server dependency

Usage: agentdesk github-sync [OPTIONS]

Argument	Value	Default	Description
--repo <REPO>	String		Repository in owner/repo form. Omit to sync all registered sync-enabled repos.

agentdesk monitoring

Monitor status commands for Discord channels

Usage: agentdesk monitoring <COMMAND>

Subcommands:

• start — Register or refresh a monitor status entry
• stop — Remove a monitor status entry

agentdesk monitoring start

Register or refresh a monitor status entry

Usage: agentdesk monitoring start [OPTIONS]

Argument	Value	Default	Description
--channel <CHANNEL> (required)	u64		Discord channel ID
--key <KEY> (required)	String		Monitor key, stable across refreshes
--description <DESCRIPTION> (required)	String		Human-readable monitor description

agentdesk monitoring stop

Remove a monitor status entry

Usage: agentdesk monitoring stop [OPTIONS]

Argument	Value	Default	Description
--channel <CHANNEL> (required)	u64		Discord channel ID
--key <KEY> (required)	String		Monitor key to remove

agentdesk intake-outbox

intake_outbox operator tools (Phase 5 of intake-node-routing)

Usage: agentdesk intake-outbox <COMMAND>

Subcommands:

• dispatched-audit — List dispatched rows and their recorded audit facts without changing them.
• dispatched-settle — Settle a dispatched handoff as unknown without creating a retry child that could redeliver an already delivered turn.
• spawned-settle — Settle a spawned handoff as unknown without creating a retry child that could redeliver an already delivered turn.
• status — Show recent intake_outbox rows (newest first).
• force-fail — Force-fail a stuck row and re-enqueue a fresh attempt. Implements transition 12 from the design doc.

agentdesk intake-outbox dispatched-audit

List dispatched rows and their recorded audit facts without changing them.

Usage: agentdesk intake-outbox dispatched-audit

agentdesk intake-outbox dispatched-settle

Settle a dispatched handoff as unknown without creating a retry child that could redeliver an already delivered turn.

Usage: agentdesk intake-outbox dispatched-settle [OPTIONS] <ID>

Argument	Value	Default	Description
<ID>	i64
--reason <REASON>	String	operator dispatched-settle via CLI

agentdesk intake-outbox spawned-settle

Settle a spawned handoff as unknown without creating a retry child that could redeliver an already delivered turn.

Usage: agentdesk intake-outbox spawned-settle [OPTIONS] <ID>

Argument	Value	Default	Description
<ID>	i64
--reason <REASON>	String	operator spawned-settle via CLI

agentdesk intake-outbox status

Show recent intake_outbox rows (newest first).

Usage: agentdesk intake-outbox status [OPTIONS]

Argument	Value	Default	Description
--channel <CHANNEL_ID>	String		Filter to a single Discord channel id.
--limit <LIMIT>	i64	20	Maximum rows to display.

agentdesk intake-outbox force-fail

Force-fail a stuck row and re-enqueue a fresh attempt. Implements transition 12 from the design doc.

Usage: agentdesk intake-outbox force-fail [OPTIONS]

Argument	Value	Default	Description
--id <ID> (required)	i64		id of the stuck row.
--reason <REASON>	String	operator force-fail via CLI	Operator's reason text recorded in last_error.

agentdesk discord

Discord utility commands without HTTP server dependency

Usage: agentdesk discord <COMMAND>

Subcommands:

• read — Read channel messages
• category-create — Create a guild category. Idempotent (list-then-create): returns the existing category when one with the same name is already present. Not safe under concurrent invocations against the same guild.
• channel-create — Create a text channel under an optional category. Idempotent by (name, parent category) via list-then-create. Not safe under concurrent invocations against the same guild.
• thread-create — Create a thread under a text/news channel or a post under a forum/media channel. Cross-process safe and idempotent by (parent, normalized name) across active and archived public threads.

agentdesk discord read

Read channel messages

Usage: agentdesk discord read [OPTIONS] <CHANNEL_ID>

Argument	Value	Default	Description
<CHANNEL_ID>	String		Discord channel ID
--limit <LIMIT>	u32		Max messages to return
--before <BEFORE>	String		Read messages before this message ID
--after <AFTER>	String		Read messages after this message ID

agentdesk discord category-create

Create a guild category. Idempotent (list-then-create): returns the existing category when one with the same name is already present. Not safe under concurrent invocations against the same guild.

Usage: agentdesk discord category-create [OPTIONS]

Argument	Value	Default	Description
--name <NAME> (required)	String		Category display name
--guild-id <GUILD_ID>	String		Override the configured guild id

agentdesk discord channel-create

Create a text channel under an optional category. Idempotent by (name, parent category) via list-then-create. Not safe under concurrent invocations against the same guild.

Usage: agentdesk discord channel-create [OPTIONS]

Argument	Value	Default	Description
--name <NAME> (required)	String		Channel display name
--category-id <CATEGORY_ID>	String		Parent category channel id
--topic <TOPIC>	String		Optional channel topic
--guild-id <GUILD_ID>	String		Override the configured guild id

agentdesk discord thread-create

Create a thread under a text/news channel or a post under a forum/media channel. Cross-process safe and idempotent by (parent, normalized name) across active and archived public threads.

Usage: agentdesk discord thread-create [OPTIONS]

Argument	Value	Default	Description
--parent-channel-id <PARENT_CHANNEL_ID> (required)	String		Parent text, news, forum, or media channel id
--name <NAME> (required)	String		Thread name
--message <MESSAGE>	String		Starter message required for forum/media parents (alias: --starter-message) (alias --starter-message)
--tag-id <TAG_IDS>...	u64 (repeatable)		Forum/media tag id to apply (repeat for multiple tags)
--auto-archive-minutes <AUTO_ARCHIVE_MINUTES>	u16	1440	Auto-archive duration in minutes (60, 1440, 4320, 10080)

agentdesk card

Kanban utility commands without HTTP server dependency

Usage: agentdesk card <COMMAND>

Subcommands:

• create — Create a card from a GitHub issue
• status — Inspect a card and connected lifecycle state

agentdesk card create

Create a card from a GitHub issue

Usage: agentdesk card create [OPTIONS]

Argument	Value	Default	Description
--from-issue <ISSUE_NUMBER> (required)	i64		GitHub issue number to import
--repo <REPO>	String		Repository in owner/repo form
--status <STATUS>	String		Target status: backlog or ready
--agent <AGENT_ID>	String		Agent assignment for ready cards

agentdesk card status

Inspect a card and connected lifecycle state

Usage: agentdesk card status [OPTIONS] <CARD_REF>

Argument	Value	Default	Description
<CARD_REF>	String		Card ID or GitHub issue number
--repo <REPO>	String		Repository in owner/repo form

agentdesk cherry-merge

Cherry-pick a worktree branch into main and optionally close its issue

Usage: agentdesk cherry-merge [OPTIONS] <BRANCH>

Argument	Value	Default	Description
<BRANCH>	String		Source branch to merge into main
--close-issue	flag		Close the linked GitHub issue when it can be inferred uniquely

agentdesk tmux-wrapper

tmux + Claude CLI integration wrapper (Unix only)

Notes: #[cfg(unix)].

Usage: agentdesk tmux-wrapper [OPTIONS] [CLAUDE_CMD]...

Argument	Value	Default	Description
--output-file <OUTPUT_FILE> (required)	String		Path to the output capture file
--input-fifo <INPUT_FIFO> (required)	String		Path to the input FIFO
--prompt-file <PROMPT_FILE> (required)	String		Path to the prompt file
--cwd <CWD>	String	.	Working directory (defaults to ".")
--input-mode <INPUT_MODE>	fifo, pipe	fifo	Input mode: fifo (default) or pipe
[CLAUDE_CMD]...	String (repeatable)		Claude command and arguments (after --) (after --)

agentdesk codex-tmux-wrapper

tmux + Codex CLI integration wrapper (Unix only)

Notes: #[cfg(unix)].

Usage: agentdesk codex-tmux-wrapper [OPTIONS]

Argument	Value	Default	Description
--output-file <OUTPUT_FILE> (required)	String		Path to the output capture file
--input-fifo <INPUT_FIFO> (required)	String		Path to the input FIFO
--prompt-file <PROMPT_FILE> (required)	String		Path to the prompt file
--codex-bin <CODEX_BIN> (required)	String		Path to codex binary
--codex-model <CODEX_MODEL>	String		Optional codex model override
--reasoning-effort <REASONING_EFFORT>	String		Optional reasoning effort (low, normal, high, xhigh)
--developer-instructions <DEVELOPER_INSTRUCTIONS>	String		Optional developer instructions passed through Codex config
--resume-session-id <RESUME_SESSION_ID>	String		Optional resume session id for the first turn
--fast-mode-state <FAST_MODE_STATE>	enabled, disabled		Override Codex native fast mode for every turn in this wrapper session
--goals-state <GOALS_STATE>	enabled, disabled		Override Codex goals feature flag for every turn in this wrapper session
--cwd <CWD>	String	.	Working directory (defaults to ".")
--add-dir <ADD_DIRS>...	String (repeatable)		Additional directory writable alongside the primary workspace
--input-mode <INPUT_MODE>	fifo, pipe	fifo	Input mode: fifo (default) or pipe
--compact-token-limit <COMPACT_TOKEN_LIMIT>	u64		Auto-compact token limit (absolute token count)

agentdesk qwen-tmux-wrapper

tmux + Qwen CLI integration wrapper (Unix only)

Notes: #[cfg(unix)].

Usage: agentdesk qwen-tmux-wrapper [OPTIONS]

Argument	Value	Default	Description
--output-file <OUTPUT_FILE> (required)	String		Path to the output capture file
--input-fifo <INPUT_FIFO> (required)	String		Path to the input FIFO
--prompt-file <PROMPT_FILE> (required)	String		Path to the prompt file
--qwen-bin <QWEN_BIN> (required)	String		Path to qwen binary
--qwen-model <QWEN_MODEL>	String		Optional qwen model override
--qwen-core-tool <QWEN_CORE_TOOLS>...	String (repeatable)		Qwen built-in core tool allowlist entry
--resume-session-id <RESUME_SESSION_ID>	String		Optional resume session id for the first turn
--fresh-session	flag		Force the first turn to start without reusing provider session state
--cwd <CWD>	String	.	Working directory (defaults to ".")
--input-mode <INPUT_MODE>	fifo, pipe	fifo	Input mode: fifo (default) or pipe

agentdesk claude-hook-relay

Relay Claude Code hook stdin JSON to the AgentDesk TUI hook receiver

Usage: agentdesk claude-hook-relay [OPTIONS]

Argument	Value	Default	Description
--endpoint <ENDPOINT> (required)	String		Hook receiver base endpoint, e.g. http://127.0.0.1:49152
--provider <PROVIDER> (required)	String		Provider id, e.g. claude
--event <EVENT> (required)	String		Claude hook event name, e.g. Stop or PreToolUse
--session-id <SESSION_ID> (required)	String		TUI session id assigned by AgentDesk

agentdesk codex-hook-relay

Relay Codex hook stdin JSON to the AgentDesk TUI hook receiver

Usage: agentdesk codex-hook-relay [OPTIONS]

Argument	Value	Default	Description
--endpoint <ENDPOINT> (required)	String		Hook receiver base endpoint, e.g. http://127.0.0.1:49152
--provider <PROVIDER> (required)	String		Provider id, e.g. codex
--event <EVENT> (required)	String		Codex hook event name, e.g. Stop or PreToolUse
--session-id <SESSION_ID> (required)	String		TUI session id assigned by AgentDesk

agentdesk reset-tmux

Kill all AgentDesk-* tmux sessions and clean temp files

Usage: agentdesk reset-tmux

agentdesk ismcptool

Check if MCP tool(s) are registered in .claude/settings.json

Usage: agentdesk ismcptool <TOOLS>...

Argument	Value	Default	Description
<TOOLS>...	String (repeatable)		Tool names to check

agentdesk addmcptool

Add MCP tool permission(s) to .claude/settings.json

Usage: agentdesk addmcptool <TOOLS>...

Argument	Value	Default	Description
<TOOLS>...	String (repeatable)		Tool names to add

agentdesk install-memento-session-hook

#2655: install (or refresh) the Memento context() SessionStart hook and a UserPromptSubmit token-pressure reminder into a Claude Code settings file. Idempotent — running twice produces the same file.

Usage: agentdesk install-memento-session-hook [OPTIONS]

Argument	Value	Default	Description
--settings-path <SETTINGS_PATH>	String		Path to the settings.json to mutate. Defaults to ~/.claude/settings.json when omitted.
--dry-run	flag		Skip writing and instead print the rendered settings to stdout.
--uninstall	flag		Remove the AgentDesk-managed memento hook entries instead of installing them. Useful when an operator wants to revert. (conflicts with dry_run)

agentdesk status

Show server health, active sessions, and auto-queue status

Usage: agentdesk status

agentdesk cards

List kanban cards

Usage: agentdesk cards [OPTIONS]

Argument	Value	Default	Description
--status <STATUS>	String		Filter by status (e.g. ready, in_progress, done)

agentdesk dispatch

Dispatch operations

Usage: agentdesk dispatch [COMMAND] [OPTIONS] [ISSUE_GROUP]...

Argument	Value	Default	Description
[ISSUE_GROUP]...	String (repeatable)		Issue groups such as 423,405 or 407
--repo <REPO>	String		Repository full name. Defaults to git remote inference when possible.
--agent <AGENT_ID>	String		Target agent id for auto-assignment and activation filtering.
--unified	flag		Legacy compatibility flag forwarded to the API.
--concurrent <CONCURRENT>	i64		Max number of concurrently active thread groups.
--no-activate	flag		Generate the run but do not activate it.

Subcommands:

• list — List active dispatches
• retry — Retry a dispatch for a card
• redispatch — Redispatch a card

agentdesk dispatch list

List active dispatches

Usage: agentdesk dispatch list

agentdesk dispatch retry

Retry a dispatch for a card

Usage: agentdesk dispatch retry <CARD_ID>

Argument	Value	Default	Description
<CARD_ID>	String		Kanban card ID

agentdesk dispatch redispatch

Redispatch a card

Usage: agentdesk dispatch redispatch <CARD_ID>

Argument	Value	Default	Description
<CARD_ID>	String		Kanban card ID

agentdesk resume

Resume a stuck kanban card from its current state

Usage: agentdesk resume [OPTIONS] <CARD_ID>

Argument	Value	Default	Description
<CARD_ID>	String		Card ID or GitHub issue number
--force	flag		Force resume (bypass guards for manual-intervention states)
--reason <REASON>	String		Reason for audit log

agentdesk advance

Complete pending dispatch and advance to review

Usage: agentdesk advance <ISSUE_NUMBER>

Argument	Value	Default	Description
<ISSUE_NUMBER>	String		GitHub issue number

agentdesk queue

Show auto-queue status with thread links

Notes: deprecated.

Usage: agentdesk queue

Deprecated compatibility command. For the queue-only inspector, use agentdesk query queue; use agentdesk query for the combined queue, dispatch, and phase-gate snapshot. This command preserves its legacy text and JSON output shapes.

agentdesk query

Unified queue + dispatch + phase-gate inspection (issue #2651).

First-class replacement for the ad-hoc curl /api/queue/status | python -c '...' polling pattern. Aggregates the queue run state, pending dispatches, and phase-gate snapshot into one structured response. Pass --json for machine-readable output.

Usage: agentdesk query [COMMAND] [OPTIONS]

Argument	Value	Default	Description
--filter <FILTERS>...	String (repeatable)		Filter result rows. Repeatable. Format: key:value (e.g. --filter status:pending, --filter dispatch_type:review). (accepted before or after the subcommand)
--agent <AGENT>	String		Restrict to a specific agent_id when applicable. (accepted before or after the subcommand)
--limit <LIMIT>	usize	0	Maximum rows to render per section (0 = unlimited). (accepted before or after the subcommand)

Subcommands:

• queue — Auto-queue run + entries snapshot (calls /api/queue/status).
• dispatches — Pending dispatches across all agents (calls /api/dispatches/pending).
• phase-gate — Phase-gate catalog + active gate state (calls /api/queue/phase-gates/catalog).
• all — All sections in one shot (default).

agentdesk query queue

Auto-queue run + entries snapshot (calls /api/queue/status).

Usage: agentdesk query queue

agentdesk query dispatches

Pending dispatches across all agents (calls /api/dispatches/pending).

Usage: agentdesk query dispatches

agentdesk query phase-gate

Phase-gate catalog + active gate state (calls /api/queue/phase-gates/catalog).

Usage: agentdesk query phase-gate

agentdesk query all

All sections in one shot (default).

Usage: agentdesk query all

agentdesk phase

Phase-gate violation snapshot (issue #2657).

Read-only inspector that flags auto-queue entries dispatched at a higher batch_phase than the run's live phase pointer. Mirrors the /adk-phase Discord slash command.

Usage: agentdesk phase [COMMAND] [OPTIONS]

Argument	Value	Default	Description
--detailed	flag		Show full per-entry detail. (accepted before or after the subcommand)

Subcommands:

• status — Show current violations (default).

agentdesk phase status

Show current violations (default).

Usage: agentdesk phase status

agentdesk deploy

Build + deploy dev + promote to release

Usage: agentdesk deploy

agentdesk agents

List agents and their status

Usage: agentdesk agents

agentdesk diag

Show turn/session diagnostics for an agent ID or Discord channel ID

Usage: agentdesk diag <IDENTIFIER>

Argument	Value	Default	Description
<IDENTIFIER>	String		Agent ID or Discord channel ID

agentdesk config

Runtime config get/set

Usage: agentdesk config <COMMAND>

Subcommands:

• get — Get current runtime config
• set — Set runtime config (JSON string)
• audit — Audit config source-of-truth drift across yaml/DB/legacy files
• sync-mcp — Sync runtime MCP servers into provider config files

agentdesk config get

Get current runtime config

Usage: agentdesk config get

agentdesk config set

Set runtime config (JSON string)

Usage: agentdesk config set <JSON>

Argument	Value	Default	Description
<JSON>	String		JSON value to set

agentdesk config audit

Audit config source-of-truth drift across yaml/DB/legacy files

Usage: agentdesk config audit [OPTIONS]

Argument	Value	Default	Description
--dry-run	flag		Preview migrations without writing files or syncing the DB

agentdesk config sync-mcp

Sync runtime MCP servers into provider config files

Usage: agentdesk config sync-mcp

agentdesk api

Call any API endpoint (curl replacement)

Usage: agentdesk api <METHOD> <PATH> [BODY]

Argument	Value	Default	Description
<METHOD>	String		HTTP method (GET, POST, PATCH, PUT, DELETE)
<PATH>	String		API path (e.g. /api/health)
[BODY]	String		Optional JSON body

agentdesk terminations

List session termination events

Usage: agentdesk terminations [OPTIONS]

Argument	Value	Default	Description
--card-id <CARD_ID>	String		Filter by kanban card ID
--dispatch-id <DISPATCH_ID>	String		Filter by dispatch ID
--session <SESSION>	String		Filter by session key
--limit <LIMIT>	u32	50	Max number of events to show

agentdesk doctor

Environment diagnostics

Usage: agentdesk doctor [OPTIONS]

Argument	Value	Default	Description
--fix	flag		Apply safe local repairs before running diagnostics
--allow-restart	flag		Allow doctor --fix to restart the dcserver service
--repair-sqlite-cache	flag		Allow doctor --fix to run SQLite schema repair and remove stale SQLite cache files
--allow-remote	flag		Allow sending configured auth tokens to a non-loopback AGENTDESK_API_URL
--profile <PROFILE>	quick, deep, security		Restrict checks to a profile

agentdesk migrate

Migration helpers

Usage: agentdesk migrate <COMMAND>

Subcommands:

• openclaw — Import OpenClaw durable state into AgentDesk

agentdesk migrate openclaw

Import OpenClaw durable state into AgentDesk

Usage: agentdesk migrate openclaw [OPTIONS] [ROOT_PATH]

Argument	Value	Default	Description
[ROOT_PATH]	String		OpenClaw root path or openclaw.json path. Defaults to the current directory. (conflicts with resume)
--agentdesk-root <PATH>	String		Override the target AgentDesk runtime root.
--agent <AGENT_ID>...	String (repeatable)		Select a specific source agent id. May be repeated. (conflicts with all_agents)
--all-agents	flag		Import every source agent. (conflicts with agent_ids)
--dry-run	flag		Print the canonical import plan without writing files.
--resume <IMPORT_ID>	String		Resume an unfinished import from $AGENTDESK_ROOT_DIR/openclaw/imports/<import_id>. (conflicts with root_path)
--fallback-provider <FALLBACK_PROVIDER>	String		Fallback provider to use when the source provider is unsupported.
--workspace-root-rewrite <OLD=NEW>...	String (repeatable)		Rewrite absolute OpenClaw workspace prefixes during import planning. May be repeated as OLD=NEW.
--write-org	flag		Preview writing config/org.yaml mutations.
--write-bot-settings	flag		Preview writing config/bot_settings.json mutations.
--write-db	flag		Preview PostgreSQL upserts.
--overwrite	flag		Preview replacing generated artifacts for the selected role(s).
--with-channel-bindings	flag		Preview Discord channel binding imports.
--with-sessions	flag		Preview lossy session import.
--snapshot-source	flag		Preview snapshotting the source tree into audit outputs.
--no-workspace	flag		Skip workspace copy while still inspecting source workspaces for prompt/memory.
--no-memory	flag		Skip Markdown memory import.
--no-prompts	flag		Skip merged prompt generation.
--tool-policy-mode <TOOL_POLICY_MODE>	String	report	Tool-policy handling mode for bot_settings import.
--discord-token-mode <DISCORD_TOKEN_MODE>	String	report	Discord token handling mode for bot_settings import.

agentdesk release-migrate-postgres

Apply pending PostgreSQL migrations before release activation

Notes: hidden from --help.

Usage: agentdesk release-migrate-postgres

agentdesk provider-cli

Provider CLI safe migration management

Usage: agentdesk provider-cli <COMMAND>

Subcommands:

• status — Show current registry channels and migration states
• plan — Show what a migration would do without running it
• upgrade — [step] Snapshot current binary and run upgrade
• smoke — [step] Run smoke checks against current or candidate binary
• canary — [step] Select a canary agent for the migration
• promote — Confirm promotion after canary passes (operator gate)
• rollback — Roll back migration to previous state
• cleanup — List paths eligible for cleanup (dry-run only — deletion not implemented)
• run — Run full migration orchestration up to CanaryActive
• resume — Resume migration from the current persisted state

agentdesk provider-cli status

Show current registry channels and migration states

Usage: agentdesk provider-cli status [OPTIONS] [PROVIDER]

Argument	Value	Default	Description
[PROVIDER]	String		Restrict output to a single provider (codex, claude, gemini, opencode, qwen)
--json	flag		Output raw JSON instead of the default table

agentdesk provider-cli plan

Show what a migration would do without running it

Usage: agentdesk provider-cli plan <PROVIDER>

Argument	Value	Default	Description
<PROVIDER>	String		Provider to plan (codex, claude, gemini, opencode, qwen)

agentdesk provider-cli upgrade

[step] Snapshot current binary and run upgrade

Use agentdesk provider-cli run for the full automated migration.

Usage: agentdesk provider-cli upgrade [OPTIONS] <PROVIDER>

Argument	Value	Default	Description
<PROVIDER>	String		Provider to upgrade
--skip-previous-preservation	flag		Skip preserving the previous binary (for mutates_in_place providers)
--candidate-path <CANDIDATE_PATH>	String		Override candidate binary path after upgrade

agentdesk provider-cli smoke

[step] Run smoke checks against current or candidate binary

Smoke is run automatically by agentdesk provider-cli run.

Usage: agentdesk provider-cli smoke [OPTIONS] <PROVIDER>

Argument	Value	Default	Description
<PROVIDER>	String		Provider to smoke-test
--channel <CHANNEL>	String	current	Channel to test: current or candidate

agentdesk provider-cli canary

[step] Select a canary agent for the migration

Canary selection is handled automatically by agentdesk provider-cli run.

Usage: agentdesk provider-cli canary [OPTIONS] <PROVIDER>

Argument	Value	Default	Description
<PROVIDER>	String		Provider to select canary for
--agent <CANARY_AGENT>	String		Explicitly request this agent as the canary

agentdesk provider-cli promote

Confirm promotion after canary passes (operator gate)

Usage: agentdesk provider-cli promote [OPTIONS] <PROVIDER>

Argument	Value	Default	Description
<PROVIDER>	String		Provider to promote
--evidence <EVIDENCE>	String		Operator note recorded in migration history

agentdesk provider-cli rollback

Roll back migration to previous state

Usage: agentdesk provider-cli rollback [OPTIONS] <PROVIDER>

Argument	Value	Default	Description
<PROVIDER>	String		Provider to roll back
--evidence <EVIDENCE>	String		Operator note recorded in migration history

agentdesk provider-cli cleanup

List paths eligible for cleanup (dry-run only — deletion not implemented)

Usage: agentdesk provider-cli cleanup <PROVIDER>

Argument	Value	Default	Description
<PROVIDER>	String		Provider to inspect

agentdesk provider-cli run

Run full migration orchestration up to CanaryActive

Usage: agentdesk provider-cli run [OPTIONS] <PROVIDER>

Argument	Value	Default	Description
<PROVIDER>	String		Provider to migrate
--candidate-path <CANDIDATE_PATH>	String		Override candidate path (skip upgrade step)
--canary-agent <CANARY_AGENT>	String		Request a specific canary agent
--skip-upgrade	flag		Skip binary preservation (use with caution)
--skip-confirm	flag		Skip operator confirmation gate after canary passes (alias --auto-promote)

agentdesk provider-cli resume

Resume migration from the current persisted state

Usage: agentdesk provider-cli resume [OPTIONS] <PROVIDER>

Argument	Value	Default	Description
<PROVIDER>	String		Provider to resume
--skip-confirm	flag		Skip operator confirmation gate after canary passes (alias --auto-promote)

agentdesk show

Inspect deterministic session-binding values (epic #2285 E1).

Usage: agentdesk show <COMMAND>

Subcommands:

• session-name — Print the expected tmux session name for a Discord channel.

agentdesk show session-name

Print the expected tmux session name for a Discord channel.

Usage: agentdesk show session-name [OPTIONS]

Argument	Value	Default	Description
--channel <CHANNEL> (required)	String		Discord channel id (or stable channel identifier) — same value AgentDesk uses when composing the tmux session name.
--provider <PROVIDER>	String		Provider to encode in the session name. Required unless the channel name ends in a registered provider suffix (-cc, -cdx, -gm, -oc, -qw). The CLI deliberately does not read live channel bindings — operator output must be reproducible from arguments alone.

agentdesk health

Show consolidated health snapshot of the current node (server status, dcserver pid, last deploy time, queue lag, Discord/disk/outbox).

Usage: agentdesk health

agentdesk machine-compare

Compare release/main/dev state across every registered worker node (mac-mini, mac-book, …). Renders a side-by-side table with dcserver pid, last deploy, queue lag, and a diff column.

Usage: agentdesk machine-compare

agentdesk activity

Time-windowed activity report: commits / closed issues / merged PRs / deploys / incidents in a single table. Uses gh + git + AgentDesk API.

Usage: agentdesk activity [OPTIONS]

Argument	Value	Default	Description
--since <SINCE> (required)	String		Window start. Accepts RFC3339 (2026-05-19T23:10:00+09:00), duration suffix (24h, 90m, 7d), or since:<sha> to anchor on a commit (commit time becomes the start).
--until <UNTIL>	String		Optional window end (RFC3339). Defaults to now when omitted.
--repo <REPO>	String		Repository in owner/repo form. Defaults to the current repo's origin remote when omitted.
--no-agentdesk	flag		Skip the AgentDesk-side deploy / incident lookup (useful when the local API is offline). Pure git + gh report.