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

# Installation

> Install the Vers CLI on macOS or Linux with a one-line curl. Alternate methods for source builds and manual binaries.

Get the Vers CLI installed in under a minute.

## Prerequisites

* **Operating System**: Linux or macOS
* **SSH Client**: Required for connecting to VMs (usually pre-installed)
* **Terminal Access**: Command-line interface

## Install the CLI

### Quick Install (Recommended)

Install the latest version of Vers CLI with a single command:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sSL https://vers.sh/api/install | bash
```

<Info>
  This script automatically detects your platform and downloads the appropriate binary to `/usr/local/bin/vers`. You may need administrative privileges for the installation.
</Info>

### Build from Source

If you prefer to build from source:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
git clone https://github.com/hdresearch/vers-cli.git
cd vers-cli
make build-and-install
```

This installs the binary to `/usr/local/bin/vers`.

### Manual Download

Download the latest release binary from [GitHub Releases](https://github.com/hdresearch/vers-cli/releases), make it executable, and move it to somewhere on your `PATH`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
chmod +x vers-*
sudo mv vers-* /usr/local/bin/vers
```

## Verify Installation

Check that Vers is properly installed:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers --version
```

You should see version information like `v0.5.1`.

## Authentication

### Get Your API Key

1. Go to [vers.sh](https://vers.sh) and log in
2. Subscribe to a plan for your organization (if you haven't already)
3. Navigate to **API Keys** in your organization settings
   * Use the org switcher in the top left to select your organization
4. Create a new API key and copy it

### Log In

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers login
```

Paste your API key when prompted. The key is stored locally at `~/.versrc`.

<Info>
  You only need to log in once per machine. To see your current API key: `cat ~/.versrc`
</Info>

## Legacy Installation Cleanup

If you previously had a development version of Vers installed and want to switch to the production version:

### Check Your Current Version

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers --version
```

If it shows `dev` instead of a version number like `v0.5.1`, follow these steps:

### Remove the Dev Version

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Check where vers is installed
which vers

# If it shows /Users/<username>/go/bin/vers, remove it
rm -rf /Users/<username>/go/bin/vers
```

### Verify the Switch

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Should now show a version number
vers --version

# Should now point to /usr/local/bin/vers
which vers
```

### Re-authenticate

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers login
# Enter your API key from vers.sh
```

## Add these docs to your AI editor

Vers hosts a Model Context Protocol (MCP) server for this documentation at `https://docs.vers.sh/mcp`. Tools like Cursor, VS Code, and Claude Code can search and read these pages directly — no scraping, no out-of-date copies.

### One-click install

<CardGroup cols={2}>
  <Card title="Add to Cursor" icon="square-terminal" href="cursor://anysphere.cursor-deeplink/mcp/install?name=vers-docs&config=eyJ1cmwiOiJodHRwczovL2RvY3MudmVycy5zaC9tY3AifQ">
    Opens Cursor and installs `vers-docs` as a remote MCP server.
  </Card>

  <Card title="Add to VS Code" icon="code" href="https://vscode.dev/redirect/mcp/install?name=vers-docs&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fdocs.vers.sh%2Fmcp%22%7D">
    Opens VS Code and installs `vers-docs` into your workspace config.
  </Card>
</CardGroup>

### Other clients

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    claude mcp add --transport http vers-docs https://docs.vers.sh/mcp
    ```
  </Tab>

  <Tab title="Cursor (manual)">
    Add to your Cursor `mcp.json`:

    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "mcpServers": {
        "vers-docs": {
          "url": "https://docs.vers.sh/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code (manual)">
    Add to `.vscode/mcp.json`:

    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "servers": {
        "vers-docs": {
          "type": "http",
          "url": "https://docs.vers.sh/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to `claude_desktop_config.json`:

    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "mcpServers": {
        "vers-docs": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://docs.vers.sh/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  This is separate from `vers mcp serve`, which exposes the Vers **platform** as MCP tools (list VMs, exec, branch, etc.). The docs MCP exposes only the docs.
</Note>

## Next Steps

With Vers installed and authenticated, you're ready to:

1. Learn the [core concepts](/concepts/overview)
2. Follow the [quickstart guide](quickstart)
3. Explore [VM access and SSH](vm-access)

## Troubleshooting

### Command not found

Make sure `/usr/local/bin` is in your `$PATH`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
echo $PATH
```

If it's not included, add it to your shell configuration (`~/.bashrc`, `~/.zshrc`, etc.):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export PATH="/usr/local/bin:$PATH"
```

### Authentication issues

* Verify your API key is correct
* Check that you have an active subscription at [vers.sh](https://vers.sh)
* Try logging out and back in: `vers logout && vers login`

### Installation script fails

Try one of these alternatives:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Run with sudo
curl -sSL https://vers.sh/api/install | sudo bash

# Or build from source
git clone https://github.com/hdresearch/vers-cli.git
cd vers-cli && make build-and-install
```

## What's next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="play" href="/quickstart">
    Boot your first VM and take your first branch in \~10 minutes.
  </Card>

  <Card title="Core concepts" icon="book-open" href="/concepts/overview">
    The mental model: projects, VMs, HEAD, branches, commits.
  </Card>

  <Card title="Configuration" icon="gear" href="/config">
    Memory, vCPUs, disk, kernel — every `vers.toml` field.
  </Card>

  <Card title="VM access" icon="terminal" href="/vm-access">
    SSH, exec, and file-transfer patterns.
  </Card>
</CardGroup>