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

# Init

# vers init

Initialize a new vers project with a vers.toml configuration file.

## Usage

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers init                                    # Initialize with defaults
vers init --name my-project                  # Set custom project name
vers init --mem-size 1024 --vcpu-count 2     # Override VM settings
```

## Options

| Option         | Default        | Description               |
| -------------- | -------------- | ------------------------- |
| `--name, -n`   | Directory name | Project name              |
| `--mem-size`   | 512            | Memory size in MiB        |
| `--vcpu-count` | 1              | Number of virtual CPUs    |
| `--rootfs`     | Project name   | Name of the rootfs image  |
| `--kernel`     | "default.bin"  | Name of the kernel image  |
| `--fs-size-vm` | 512            | VM filesystem size in MiB |

## Examples

### Initialize with defaults

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

### Customize project settings

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers init --name my-web-app --mem-size 1024 --vcpu-count 2
```

### Machine learning project

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers init --name ml-experiment --mem-size 2048 --vcpu-count 4
```

## What gets created

### Configuration file (`vers.toml`)

```toml theme={"theme":{"light":"min-light","dark":"min-dark"}}
[machine]
mem_size_mib = 512
vcpu_count = 1
fs_size_mib = 512

[rootfs]
name = "my-project"

[kernel]
name = "default.bin"
```

### Repository structure (`.vers/`)

```
.vers/
├── HEAD              # Current VM pointer (initially empty)
└── logs/             # Log storage
```

### Git integration (`.gitignore`)

Automatically creates or updates `.gitignore` to exclude Vers internals from version control.

## How it works

The `init` command:

1. **Authentication check**: Prompts for login if no API key exists
2. **Directory creation**: Creates `.vers/` directory structure
3. **Configuration**: Generates `vers.toml` with specified or default values
4. **Git integration**: Creates/updates `.gitignore` with Vers-specific entries
5. **Local setup**: Initializes empty HEAD file

## Authentication

If this is your first time using Vers, `init` will prompt you to authenticate:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers init
# Prompts for login if not already authenticated
```

## Configuration details

The generated `vers.toml` uses these sections:

* **\[machine]**: VM resource allocation (memory, CPU, storage)
* **\[rootfs]**: Base filesystem image configuration
* **\[kernel]**: Kernel image specification

You can edit `vers.toml` after initialization to adjust settings.

## Prerequisites

* Write permissions in the current directory
* Network connectivity for authentication (if not already logged in)

## Common Patterns

### New project, fast path

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
mkdir my-project && cd my-project
vers init
vers run --wait
```

### Init with custom sizing baked in

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers init --mem-size 4096 --vcpu-count 4 --fs-size-vm 4096
```

### Re-init an existing directory

`vers init` won't overwrite an existing `vers.toml`. To regenerate, remove and re-run:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
rm vers.toml
vers init --mem-size 2048
```

## See Also

* [vers run](/cli-reference/run) - Start your environment after initialization
* [vers login](/cli-reference/login) - Authenticate with Vers platform