# Multica CLI Commands for Daemon and Workspace Management: Complete Guide

> Master Multica CLI commands for daemon and workspace management. Control agent runtime and sync cloud workspaces with this comprehensive guide.

- Repository: [multica-ai/multica](https://github.com/multica-ai/multica)
- Tags: how-to-guide
- Published: 2026-04-11

---

**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`](https://github.com/multica-ai/multica/blob/main/main.go).

## Daemon Management Commands

The daemon command tree is implemented in [`server/cmd/multica/cmd_daemon.go`](https://github.com/multica-ai/multica/blob/main/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`](https://github.com/multica-ai/multica/blob/main/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`](https://github.com/multica-ai/multica/blob/main/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`](https://github.com/multica-ai/multica/blob/main/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`](https://github.com/multica-ai/multica/blob/main/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`](https://github.com/multica-ai/multica/blob/main/internal/cli/config.go).

## Practical Usage Examples

### Daemon Lifecycle Management

```bash

# 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

```bash

# 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`](https://github.com/multica-ai/multica/blob/main/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`](https://github.com/multica-ai/multica/blob/main/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`](https://github.com/multica-ai/multica/blob/main/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`](https://github.com/multica-ai/multica/blob/main/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`](https://github.com/multica-ai/multica/blob/main/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`](https://github.com/multica-ai/multica/blob/main/server/internal/daemon/daemon.go). This returns the daemon’s current uptime, active agent count, and watched workspace status.