> ## 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.

# CLI overview

> Every Vers command at a glance. Four primitives for the tree, everything else is convenience.

The Vers CLI is deliberately small. Four commands make the tree:

|                                                |                                                           |
| ---------------------------------------------- | --------------------------------------------------------- |
| [`vers run`](/cli-reference/run)               | Boot a root VM                                            |
| [`vers branch`](/cli-reference/branch)         | Fork a live VM in 258µs                                   |
| [`vers commit`](/cli-reference/commit)         | Freeze a VM as an immutable, content-addressable snapshot |
| [`vers run-commit`](/cli-reference/run-commit) | Restore any snapshot to a fresh VM, anywhere              |

Everything else is convenience: scaffolding a project, connecting to a VM, naming things, moving HEAD around.

## Project

<CardGroup cols={3}>
  <Card title="vers init" icon="folder-plus" href="/cli-reference/init">
    Create a project and generate `vers.toml`.
  </Card>

  <Card title="vers run" icon="play" href="/cli-reference/run">
    Boot a VM from your configuration.
  </Card>

  <Card title="vers run-commit" icon="arrow-rotate-left" href="/cli-reference/run-commit">
    Restore a VM from a committed snapshot.
  </Card>

  <Card title="vers build" icon="hammer" href="/cli-reference/build">
    Build a commit from a Dockerfile.
  </Card>

  <Card title="vers deploy" icon="rocket" href="/cli-reference/deploy">
    Clone, install, build, and run a GitHub repo on a fresh VM.
  </Card>
</CardGroup>

## Tree

<CardGroup cols={3}>
  <Card title="vers branch" icon="code-branch" href="/cli-reference/branch">
    Fork a live VM or commit into a new branch.
  </Card>

  <Card title="vers checkout" icon="location-crosshairs" href="/cli-reference/checkout">
    Move HEAD to a different VM.
  </Card>

  <Card title="vers commit" icon="camera" href="/cli-reference/commit">
    Snapshot a VM as an immutable commit.
  </Card>

  <Card title="vers tag" icon="bookmark" href="/cli-reference/tag">
    Named, mutable pointers to commits.
  </Card>

  <Card title="vers repo" icon="folder-tree" href="/cli-reference/repo">
    Group commits into named, optionally public repositories.
  </Card>
</CardGroup>

## VM

<CardGroup cols={3}>
  <Card title="vers connect" icon="terminal" href="/cli-reference/connect">
    Interactive SSH into a VM.
  </Card>

  <Card title="vers execute" icon="bolt" href="/cli-reference/execute">
    Run a one-off command on a VM.
  </Card>

  <Card title="vers copy" icon="arrows-left-right" href="/cli-reference/copy">
    Transfer files to or from a VM.
  </Card>

  <Card title="vers info" icon="circle-info" href="/cli-reference/info">
    Detailed metadata: IP, lineage, timestamps.
  </Card>

  <Card title="vers tunnel" icon="right-left" href="/cli-reference/tunnel">
    Forward a local port to a VM port.
  </Card>

  <Card title="vers pause" icon="pause" href="/cli-reference/pause">
    Suspend a VM.
  </Card>

  <Card title="vers resume" icon="circle-play" href="/cli-reference/resume">
    Resume a paused VM.
  </Card>

  <Card title="vers resize" icon="expand" href="/cli-reference/resize">
    Grow a VM's disk.
  </Card>

  <Card title="vers kill" icon="power-off" href="/cli-reference/kill">
    Terminate a VM.
  </Card>

  <Card title="vers status" icon="chart-simple" href="/cli-reference/status">
    HEAD + VM states at a glance.
  </Card>
</CardGroup>

## Environment

<CardGroup cols={2}>
  <Card title="vers env" icon="file-lines" href="/cli-reference/env">
    Inject environment variables into newly-created VMs.
  </Card>
</CardGroup>

## Auth

<CardGroup cols={3}>
  <Card title="vers signup" icon="user-plus" href="/cli-reference/signup">
    Create a Vers account.
  </Card>

  <Card title="vers login" icon="right-to-bracket" href="/cli-reference/login">
    Authenticate the CLI against your Vers account.
  </Card>

  <Card title="vers logout" icon="right-from-bracket" href="/cli-reference/logout">
    Clear local credentials.
  </Card>
</CardGroup>

## Utility

<CardGroup cols={2}>
  <Card title="vers alias" icon="tag" href="/cli-reference/alias">
    Human-readable names for VM IDs.
  </Card>

  <Card title="vers head" icon="crosshairs" href="/cli-reference/head">
    Print the HEAD VM ID. Scripting primitive.
  </Card>

  <Card title="vers upgrade" icon="arrow-up" href="/cli-reference/upgrade">
    Upgrade the CLI in place.
  </Card>

  <Card title="vers mcp" icon="plug" href="/cli-reference/mcp">
    Model Context Protocol server for AI agents.
  </Card>
</CardGroup>

## Reading a reference page

Every command page follows the same shape:

```
# vers <command>

Short one-sentence description.

## Synopsis      ← every form of the command
## Description   ← what it actually does
## Basic Usage   ← the 2-3 shapes you'll use most
## Options       ← every flag
## Examples      ← real scenarios
```

If you're scanning, start at **Synopsis**; if you're stuck, start at **Examples**.