Multica CLI Commands for Daemon and Workspace Management: Complete Guide

The Multica CLI provides eight primary sub-commands—daemon start|stop|status|logs and workspace list|get|watch|unwatch|members—to control the background agent runtime and synchronize local development environments with cloud workspaces.

The multica-ai/multica repository ships a Go-based CLI that exposes two critical command trees for local development workflow. These Multica CLI commands enable developers to manage the persistent agent daemon and configure which remote workspaces the local machine monitors and executes tasks for. All sub-commands are registered in init() functions within the server/cmd/multica package and stitched into the root command defined in main.go.

Daemon Management Commands

The daemon command tree is implemented in server/cmd/multica/cmd_daemon.go, which defines the daemonCmd structure and its sub-commands. This controls the local agent-runtime process that polls the Multica backend and executes AI agents.

Start the Background Agent

Use multica daemon start to launch the daemon. According to the source in cmd_daemon.go, this invokes buildDaemonStartArgs (lines 96–130) to construct the process arguments, then branches based on the --foreground flag:

• multica daemon start: Spawns a detached background process via runDaemonBackground
• multica daemon start --foreground: Runs the daemon in the current terminal via runDaemonForeground (useful for debugging)

The daemon writes a PID file and log file to ~/.multica/ using profile-specific paths generated by daemonPIDPathForProfile and daemonLogPathForProfile.

Stop and Monitor the Daemon

Control and inspect the running process with these commands:

• multica daemon stop: Sends a graceful termination signal to the PID stored in the profile directory
• multica daemon status: Reports PID, uptime, agent count, and watched workspaces; add --output json for machine-readable format

Status checks query a local HTTP endpoint (/health) on a profile-specific port determined by healthPortForProfile.

Stream Daemon Logs

Access the daemon's log output without locating the file manually:

• multica daemon logs: Prints the log file from daemonLogPathForProfile
• multica daemon logs --follow: Tails the log in real-time (equivalent to tail -f)
• multica daemon logs -n <lines>: Limits output to the last N lines

Workspace Management Commands

The workspace command tree lives in server/cmd/multica/cmd_workspace.go, defining workspaceCmd and its sub-commands. These interact with the Multica backend API while updating local CLI configuration stored in server/internal/cli/config.go.

List and Inspect Workspaces

Query workspace information and membership:

• multica workspace list: Displays all workspaces you belong to, marking watched workspaces with an asterisk (*)
• multica workspace get <workspace-id>: Retrieves detailed metadata for a specific workspace; supports --output json for scripting
• multica workspace members <workspace-id>: Lists all members and their assigned roles within the workspace

Configure Workspace Watching

Manage which workspaces the local daemon monitors for agent tasks:

• multica workspace watch <workspace-id>: Adds the workspace to your local configuration via cfg.AddWatchedWorkspace (lines 28–32 of cmd_workspace.go). If this is the first watched workspace, it automatically becomes the default. The daemon will begin polling this workspace for executable agent tasks.

• multica workspace unwatch <workspace-id>: Removes the workspace from the watch list via cfg.RemoveWatchedWorkspace (lines 55–57), stopping the daemon from monitoring it.

Both commands persist data to a slice of WatchedWorkspace structs managed by the CLI configuration in internal/cli/config.go.

Practical Usage Examples

Daemon Lifecycle Management

# Start daemon in background (production mode)

multica daemon start

# Debug mode: start in foreground to see real-time logs

multica daemon start --foreground

# Check status as JSON for automation

multica daemon status --output json

# Stop the daemon gracefully

multica daemon stop --profile dev

# Follow logs indefinitely

multica daemon logs -f

Workspace Synchronization

# View all workspaces with watch status

multica workspace list

# Get workspace details

multica workspace get 123e4567-e89b-12d3-a456-426614174000

# Start monitoring a workspace

multica workspace watch 123e4567-e89b-12d3-a456-426614174000

# Remove from local monitoring

multica workspace unwatch 123e4567-e89b-12d3-a456-426614174000

Summary

• Daemon commands (start, stop, status, logs) control the local agent runtime defined in cmd_daemon.go, managing process lifecycle via PID files in ~/.multica/ and exposing health checks on a local HTTP port.
• Workspace commands (list, get, members, watch, unwatch) configure which remote workspaces the daemon polls, storing state in internal/cli/config.go through AddWatchedWorkspace and RemoveWatchedWorkspace functions.
• Both command trees register via init() functions in the Cobra-based CLI structure defined in server/cmd/multica/main.go.

Frequently Asked Questions

How do I run the Multica daemon in debug mode?

Use multica daemon start --foreground to keep the process attached to your terminal instead of spawning a background process. This invokes runDaemonForeground directly, allowing you to view real-time agent execution logs without accessing the log file separately.

Where does the Multica CLI store daemon state files?

The daemon writes its process ID file and log file to the user’s profile directory under ~/.multica/, using profile-specific paths generated by daemonPIDPathForProfile and daemonLogPathForProfile. The CLI configuration, including watched workspaces, is stored separately in server/internal/cli/config.go as a serialized slice of WatchedWorkspace structs.

What happens when I watch a workspace in Multica?

The multica workspace watch command adds the workspace ID to your local configuration via cfg.AddWatchedWorkspace (lines 28–32 of cmd_workspace.go), causing the daemon to poll that workspace for agent tasks. If no default workspace is set, the watched workspace automatically becomes the default for subsequent CLI operations.

How does the CLI check if the daemon is healthy?

The multica daemon status command queries a local HTTP GET request to /health on a profile-specific port determined by healthPortForProfile, as implemented in the core daemon logic within server/internal/daemon/daemon.go. This returns the daemon’s current uptime, active agent count, and watched workspace status.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}