diff --git a/CLI_AND_DAEMON.md b/CLI_AND_DAEMON.md index 5d59c10b..4d0f4927 100644 --- a/CLI_AND_DAEMON.md +++ b/CLI_AND_DAEMON.md @@ -8,7 +8,7 @@ The `multica` CLI connects your local machine to Multica. It handles authenticat ```bash brew tap multica-ai/tap -brew install multica-cli +brew install multica ``` ### Build from Source diff --git a/CLI_INSTALL.md b/CLI_INSTALL.md new file mode 100644 index 00000000..213006f5 --- /dev/null +++ b/CLI_INSTALL.md @@ -0,0 +1,171 @@ +# Multica CLI — Installation Guide for AI Agents + +> **Audience:** This document is designed for AI agents (Claude Code, Codex, etc.) to read and execute step-by-step. Each step includes the exact shell commands to run, expected outcomes, and error handling. + +## One-Line Instruction for Users + +Give this instruction to your AI agent: + +``` +Fetch https://github.com/multica-ai/multica/blob/main/CLI_INSTALL.md and follow the instructions to install Multica CLI, log in, and start the daemon on this machine. +``` + +--- + +## Step 1: Check if Multica CLI is already installed + +Run: + +```bash +multica version +``` + +- **If it prints a version string** (e.g. `multica v0.x.x`): skip to **Step 3**. +- **If command not found**: continue to **Step 2**. + +--- + +## Step 2: Install the Multica CLI + +### Option A: Homebrew (preferred) + +Check if Homebrew is available: + +```bash +which brew +``` + +If `brew` is found, install via Homebrew: + +```bash +brew tap multica-ai/tap && brew install multica +``` + +Then verify: + +```bash +multica version +``` + +If the version prints successfully, skip to **Step 3**. + +### Option B: Download from GitHub Releases (no Homebrew) + +If Homebrew is not available, download the binary directly. + +Detect OS and architecture, then download the correct archive: + +```bash +OS=$(uname -s | tr '[:upper:]' '[:lower:]') # "darwin" or "linux" +ARCH=$(uname -m) # "x86_64" or "arm64" + +# Normalize architecture name +if [ "$ARCH" = "x86_64" ]; then + ARCH="amd64" +fi + +# Get the latest release tag from GitHub +LATEST=$(curl -sI https://github.com/multica-ai/multica/releases/latest | grep -i '^location:' | sed 's/.*tag\///' | tr -d '\r\n') + +# Download and extract +curl -sL "https://github.com/multica-ai/multica/releases/download/${LATEST}/multica_${OS}_${ARCH}.tar.gz" -o /tmp/multica.tar.gz +tar -xzf /tmp/multica.tar.gz -C /tmp multica +sudo mv /tmp/multica /usr/local/bin/multica +rm /tmp/multica.tar.gz +``` + +Verify: + +```bash +multica version +``` + +**If this fails:** +- Check that `/usr/local/bin` is in `$PATH`. +- On Linux, you may need `chmod +x /usr/local/bin/multica`. +- If `sudo` is not available, install to a user-writable directory: `mv /tmp/multica ~/.local/bin/multica` and ensure `~/.local/bin` is in `$PATH`. + +--- + +## Step 3: Log in + +Run: + +```bash +multica login +``` + +**Important:** This command opens a browser window for OAuth authentication. Tell the user: + +> "A browser window will open for Multica login. Please complete the authentication in your browser, then come back here." + +Wait for the command to complete. It will automatically discover and watch all workspaces the user belongs to. + +Verify: + +```bash +multica auth status +``` + +Expected output should show the authenticated user and server URL. + +**If login fails:** +- If no browser is available (headless environment), the user can generate a Personal Access Token at `https://app.multica.ai/settings` and run: `multica login --token` +- If the server URL needs to be customized: `multica config set server_url ` before logging in. + +--- + +## Step 4: Start the daemon + +First, check if the daemon is already running: + +```bash +multica daemon status +``` + +- **If status is "running"**: skip to **Step 5**. +- **If status is "stopped"**: start it: + +```bash +multica daemon start +``` + +Wait 3 seconds, then verify: + +```bash +multica daemon status +``` + +Expected output should show `running` status with detected agents (e.g. `claude`, `codex`). + +**If daemon fails to start:** +- Check logs: `multica daemon logs` +- If a port conflict occurs, the daemon may already be running under a different profile. +- If no agents are detected, ensure at least one AI CLI (`claude` or `codex`) is installed and on the `$PATH`. + +--- + +## Step 5: Verify everything is working + +Run: + +```bash +multica daemon status +``` + +Confirm: +1. Status is `running` +2. At least one agent is listed (e.g. `claude`, `codex`) +3. At least one workspace is being watched + +If the agents list is empty, tell the user: + +> "The Multica daemon is running but no AI agent CLIs were detected. Please install at least one: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`) or [Codex](https://github.com/openai/codex) (`codex`), then restart the daemon with `multica daemon stop && multica daemon start`." + +--- + +## Summary + +When all steps are complete, inform the user: + +> "Multica CLI is installed and the daemon is running. Agents in your workspaces can now execute tasks on this machine. You can manage workspaces with `multica workspace list` and view daemon logs with `multica daemon logs -f`." diff --git a/README.md b/README.md index 04fbb477..2242bddb 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,14 @@ See the [Self-Hosting Guide](SELF_HOSTING.md) for full instructions. The `multica` CLI connects your local machine to Multica — authenticate, manage workspaces, and run the agent daemon. +**Option A — paste this to your coding agent (Claude Code, Codex, etc.):** + +``` +Fetch https://github.com/multica-ai/multica/blob/main/CLI_INSTALL.md and follow the instructions to install Multica CLI, log in, and start the daemon on this machine. +``` + +**Option B — install manually:** + ```bash # Install brew tap multica-ai/tap diff --git a/README.zh-CN.md b/README.zh-CN.md index be856054..45b31149 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -70,6 +70,14 @@ make start # 启动应用 `multica` CLI 将你的本地机器连接到 Multica — 用于认证、管理工作区和运行 Agent daemon。 +**方式 A — 将以下指令粘贴给你的 coding agent（Claude Code、Codex 等）：** + +``` +Fetch https://github.com/multica-ai/multica/blob/main/CLI_INSTALL.md and follow the instructions to install Multica CLI, log in, and start the daemon on this machine. +``` + +**方式 B — 手动安装：** + ```bash # 安装 brew tap multica-ai/tap