> ## Documentation Index
> Fetch the complete documentation index at: https://hubify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Hubify CLI on macOS, Linux, or Windows. Optionally configure the MCP server for Claude Code or Codex.

# Installation

## npm (Recommended)

```bash theme={null}
npm install -g hubify-labs
```

Requires Node.js 18 or later. Installs both the `hubify` CLI and the `hubify mcp`
launcher (which starts the Hubify MCP server for AI coding assistants).

## Homebrew (macOS)

```bash theme={null}
brew tap hubify/tap
brew install hubify
```

## curl (Linux / macOS)

```bash theme={null}
curl -fsSL https://get.hubify.com | sh
```

This downloads the latest binary and installs it to `/usr/local/bin/hubify`.

## Verify Installation

```bash theme={null}
hubify --version
```

You should see a version number printed (e.g. `1.0.0`). If you get
`command not found`, ensure your npm global bin directory is in your `PATH`
(see Troubleshooting below).

## Update

```bash theme={null}
# npm
npm update -g hubify-labs

# Homebrew
brew upgrade hubify

# curl
curl -fsSL https://get.hubify.com | sh
```

## Uninstall

```bash theme={null}
# npm
npm uninstall -g hubify-labs

# Homebrew
brew uninstall hubify

# curl
rm /usr/local/bin/hubify
```

***

## Using with Claude Code

After installing the CLI, add the Hubify MCP server to Claude Code so Claude
can read and write your lab data directly.

<Note>
  The `hubify mcp` launcher is available in hubify-labs **2.0.0 and later**.
  Run `hubify --version` to confirm your installed version is current.
</Note>

### Option A: `claude mcp add` (one command)

```bash theme={null}
claude mcp add hubify -- hubify mcp
```

Then set your lab context:

```bash theme={null}
claude mcp add hubify \
  -e CONVEX_URL="https://your-deployment.convex.cloud" \
  -e HUBIFY_LAB_SLUG="your-lab-slug" \
  -- hubify mcp
```

Find your `CONVEX_URL` and lab slug under **Settings → Developer** in the Hubify
web app.

### Option B: manual `~/.claude/mcp.json`

Create or merge into `~/.claude/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "hubify": {
      "command": "hubify",
      "args": ["mcp"],
      "env": {
        "CONVEX_URL": "https://your-deployment.convex.cloud",
        "HUBIFY_LAB_SLUG": "your-lab-slug"
      }
    }
  }
}
```

### Verify Claude Code sees the server

Restart Claude Code, then run:

```bash theme={null}
claude mcp list
```

Expected line: `hubify   connected   48 tools`

Run the health check to confirm env resolution:

```bash theme={null}
hubify mcp --health
```

For the full Claude Code setup walkthrough, see [MCP Setup](/docs/mcp/setup).

***

## Using with Codex

After installing the CLI:

```bash theme={null}
# Set env vars before starting Codex
export CONVEX_URL="https://your-deployment.convex.cloud"
export HUBIFY_LAB_SLUG="your-lab-slug"

# Point Codex at the MCP server
export CODEX_MCP_SERVERS='{"hubify":{"command":"hubify","args":["mcp"]}}'

codex
```

Or add to your Codex config file (`~/.codex/config.json`):

```json theme={null}
{
  "mcpServers": {
    "hubify": {
      "command": "hubify",
      "args": ["mcp"],
      "env": {
        "CONVEX_URL": "https://your-deployment.convex.cloud",
        "HUBIFY_LAB_SLUG": "your-lab-slug"
      }
    }
  }
}
```

***

## Requirements

| Requirement      | Version                     |
| ---------------- | --------------------------- |
| Node.js          | 18+ (for npm install)       |
| Operating System | macOS, Linux, Windows (WSL) |
| Terminal         | Any terminal emulator       |
| Shell            | bash, zsh, fish             |

## Proxy / Firewall

If you are behind a corporate proxy:

```bash theme={null}
export HTTPS_PROXY=https://proxy.example.com:8080
hubify auth login
```

The CLI communicates with `www.hubify.com/api` over HTTPS (port 443).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found after npm install">
    Ensure your npm global bin directory is in your PATH:

    ```bash theme={null}
    export PATH="$(npm config get prefix)/bin:$PATH"
    ```
  </Accordion>

  <Accordion title="Permission denied on Linux">
    Avoid `sudo npm install -g`. Instead, configure npm to use a user directory:

    ```bash theme={null}
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    export PATH=~/.npm-global/bin:$PATH
    ```
  </Accordion>

  <Accordion title="Node.js version too old">
    Use nvm to install a newer version:

    ```bash theme={null}
    nvm install 20
    nvm use 20
    npm install -g hubify-labs
    ```
  </Accordion>

  <Accordion title="Claude Code MCP shows 'failed' instead of 'connected'">
    1. Confirm `hubify mcp --health` passes all checks
    2. Confirm `hubify --version` works (CLI is on PATH)
    3. Check that `CONVEX_URL` and `HUBIFY_LAB_SLUG` are set in your mcp.json env block
    4. Restart Claude Code -- MCP servers are loaded at session start, not hot-reloaded
  </Accordion>
</AccordionGroup>