CLI reference

The harmony command is the scriptable counterpart to the desktop, attached to the same daemon.

harmony and nala are the same command. harmony is the name to learn; nala is the original name for the same binary and still works everywhere — same verbs, same behaviour, no deprecation. Every command on this page is valid under either name.

wmux is a third name on the same binary, but it is not an alias: it is the original multiplexer surface, and the workspace, pane and input verbs live there. All three shims are installed on your PATH.

Two shorthands worth knowing:

• harmony — launch the agent in the current terminal
• harmony . — open the current directory as a workspace in the desktop app (any path works: harmony ../other-project)

Core

harmony                                 Open the interactive TUI
harmony "initial prompt"                Open the TUI with an initial prompt
harmony run "prompt" [options]          Run a noninteractive task
harmony ask "prompt"                    Ask a question (ask mode)
harmony plan "prompt"                   Plan-mode execution
harmony sit                             Launch or focus Harmony Desktop (alias: harmony desktop)
harmony desktop [--attach <sessionId>]  Open or focus Harmony Desktop desktop
harmony update [--check]                Check for and install updates
harmony version                         Print version information
harmony help [command]                  Show help
harmony doctor [--json] [--fix-safe]    Run health diagnostics

Daemon management

harmony daemon start                    Start the daemon
harmony daemon status                   Show daemon status
harmony daemon logs                     Show recent daemon logs
harmony daemon restart                  Restart the daemon
harmony daemon stop                     Stop the daemon (refuses if work is active)

Sessions

harmony sessions list                   List all sessions
harmony sessions show <id>              Show session details
harmony sessions attach-metadata <id>   Show attachment metadata
harmony sessions archive <id>           Archive a session
harmony attach <sessionId>              Attach to an existing session
harmony resume <sessionId>              Resume a paused session

Providers

harmony providers list                  List available providers
harmony providers probe <name>          Probe a specific provider
harmony providers status                Show provider authentication status

Tasks, agents, artifacts

harmony tasks list|create|close         Manage tasks
harmony agents list                     List and manage agents
harmony artifacts list|export           Inspect session artifacts
harmony agent send --task <taskId> --to <agentId> --message "ready" --from <agentId>
harmony agent inbox --agent <agentId> --unread
harmony provider settings --yolo-on --a2a connect
harmony capabilities                    List supported RPC methods
harmony diagnostics --json              Machine-readable diagnostics

Channels

wmux channel list                    Channels visible to your workspace
wmux channel join <ch>               Join a public channel
wmux channel post <ch> <text…>       Post a message
wmux channel read <ch> [--since <seq>]  Print messages, oldest first
wmux channel unread [--member <id>]  Unread + mention counts
wmux channel ack <ch> <uptoSeq|all>  Mark consumed

Workspaces, panes, browser

wmux list-workspaces                 List all workspaces
wmux new-workspace [--name <name>] [--cwd <dir>]
wmux focus-workspace <id>
wmux current-workspace
wmux new-surface                     Open a new surface (terminal tab)
wmux list-panes                      List panes in the active workspace
wmux split [--direction right|down]
wmux send <text> [--submit]          Send text to your own pane
wmux send-key <keystroke>            Send a key (Enter, ctrl-c, Tab)
wmux read-screen [--tail <n>]        Read the current screen
wmux open <url> [--workspace <id>]   Open/reuse a browser pane
wmux browser navigate <url>
wmux browser session start [--profile <name>]
wmux browser close

Voice

harmony speak "text"                    System TTS, desktop closed
harmony dictate --wav recording.wav     Local faster-whisper transcription
harmony voice status                    Voice subsystem status

Configuration, MCP, observability

harmony config get [key]                Read configuration
harmony config set <key> <value>        Set a value
harmony config unset <key>              Remove a value
harmony config path                     Show the config file path
harmony config validate                 Validate the config file
wmux mcp check                       Show MCP registration status
wmux mcp register                    Register nala with ~/.claude.json
wmux mcp unregister                  Remove registration
wmux setup-hooks                     Install Claude Code hooks
harmony trace tail                      Tail the event trace stream
harmony trace export [--format json|jsonl]

Notes

• Piped and scripted output is machine-readable; the launch banner never appears in noninteractive output.
• harmony doctor --fix-safe repairs the safe class of problems (paths, shims, registration) automatically.
• Workspace identity is required for channel and agent mutations: outside a Harmony pane they fail closed.