> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diversion.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Quickstart
> Set up Diversion as the version control for your coding agent
This page is written for **AI coding agents** (Claude Code, Cursor, Codex, or any tool that runs shell commands). It explains how to use Diversion as the version control for a repository with the `dv` CLI. Diversion is a cloud-native version control system — an alternative to Git and Perforce, built for large binary files with automatic sync.
**Use Diversion when** your repo has large or binary files (game assets, models, datasets, build artifacts) that Git and Git LFS handle poorly, when you want commits to sync to teammates automatically (no push or pull), or when you're running multiple agents that each need an isolated copy of the repo.
Setting up Diversion yourself with the desktop app? Start with the [Quickstart](/quickstart) instead.
**Pointing an agent here?** The full machine-readable docs index lives at [`docs.diversion.dev/llms.txt`](https://docs.diversion.dev/llms.txt) (and [`/llms-full.txt`](https://docs.diversion.dev/llms-full.txt) for the complete text). Give your agent that URL together with this page.
## How Diversion differs from Git
Diversion is not Git. Internalize these rules before running commands:
* **Auto-sync — no `push` or `pull`.** Every commit replicates to the cloud and to teammates automatically. There is no `dv push` or `dv pull`.
* **No staging area — no `git add`.** Diversion tracks every change in the working tree continuously. You commit files directly.
* **One workspace = one working directory.** A *workspace* is a local copy of a single branch. To work on two branches at once, use two workspaces — see [Run agents in parallel](#run-agents-in-parallel).
* **Always pass a subcommand.** Run `dv status`, `dv commit`, and so on. Running bare `dv` opens an interactive shell; avoid it in non-interactive or agent contexts.
## Install
```bash theme={null}
curl -sL https://get.diversion.dev/unix | bash ; export PATH="$HOME/.diversion/bin:$PATH"
```
Add the `export PATH` line to your shell profile (`~/.bashrc` or `~/.zshrc`) to make it permanent.
Download and run the [Windows installer](https://get.diversion.dev/win).
Confirm the install:
```bash theme={null}
dv version
```
## Authenticate
```bash theme={null}
dv login
```
This opens a browser to sign in. **A human runs this once** in the environment where the agent operates; the agent reuses the session afterward.
**Headless or CI agents (no browser):** generate an API token (in the web app: avatar → **Integrations** → **Generate a new API token**) and authenticate non-interactively with `dv authenticate ` — no browser needed. The [CI/CD guide](/ci-cd) has the full setup. The same token also works as a `Bearer` token against the [REST API](/api-reference/introduction). API access requires the [Pro plan or above](https://www.diversion.dev/pricing).
## Core commands
```bash theme={null}
# Start tracking a new project in the current directory
dv init
# Get a working copy of an existing repository
dv clone [path]
# See what changed in the working tree
dv status
# Commit all current changes (replicates automatically — no push needed)
dv commit -a -m "your message"
# Create a new branch and switch to it
dv branch -c
# Switch to an existing branch, commit, or tag
dv checkout [
# Merge another branch into the current one
dv merge
# View history
dv log
```
Full reference: [CLI Reference](/cmd-ref/about-cmd).
## Git → Diversion command map
| Git | Diversion (`dv`) |
| ---------------------------------- | ------------------------------------------------------- |
| `git clone ` | `dv clone [path]` |
| `git init` | `dv init` |
| `git add ` | *(not needed — changes are tracked automatically)* |
| `git status` | `dv status` |
| `git commit -am "msg"` | `dv commit -a -m "msg"` |
| `git push` / `git pull` | *(not needed — auto-sync)* |
| `git checkout -b ` | `dv branch -c ` |
| `git switch ` | `dv checkout ` |
| `git merge ` | `dv merge ` |
| `git log` | `dv log` |
| `git worktree add ` | `dv clone --new-workspace --ref ` |
## Run agents in parallel
To run agents in isolated workspaces — the Diversion equivalent of `git worktree` — clone the repository into a separate directory with its own workspace, **each on its own branch**. The workspaces are isolated on disk, and a dedicated branch per agent keeps their commits from interfering. (Agents that share a branch still auto-sync to it and can conflict — give each one its own branch.)
```bash theme={null}
# Create an isolated workspace on a dedicated branch
dv clone /tmp/-agent-1 --new-workspace --ref
```
The agent works inside `/tmp/-agent-1` and commits as usual — changes auto-sync to that branch. When the work is done, tear the workspace down:
```bash theme={null}
dv workspace # list workspaces to find the one to remove (id starts with dv.ws.)
dv unregister -f # run from inside /tmp/-agent-1 — detaches the local copy
dv workspace delete -f
rm -rf /tmp/-agent-1
```
Today this clones the full repository, including binary assets. For asset-heavy repositories (e.g. Unreal projects) that is a large download per workspace. Code-only ("selective sync") cloning from the CLI is on the roadmap.
## Next steps
The Diversion plugin for Claude Code links every commit to the conversation that produced it, so you can ask later *why* any change was made. Optional.
Every `dv` command, flag, and argument.
Automate Diversion over REST.
Diversion's built-in AI coding agent.
]