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

# graft init

> Initialize Graft on a target container.

# `graft init`

Initialize Graft on a target database container. This is the first command you run — it bridges the container's Docker volume to the host filesystem and sets up the Graft project structure.

## Usage

```bash theme={null}
graft init <container> [flags]
```

## Behavior

1. Inspects the target container (image, env, ports, network, volumes)
2. Prompts you to select which Docker volume contains the database data
3. Stops the container
4. Copies data from the Docker volume to `~/.graft/<container>/branches/main/` via an ephemeral Alpine runner
5. Sets up the `graft.db` SQLite DAG store and `objects/` directory
6. If `--bind`, recreates the container with a host bind mount
7. Starts the container
8. Saves the state to `config.json`

## Flags

| Flag       | Alias | Default | Description                                              |
| ---------- | ----- | ------- | -------------------------------------------------------- |
| `--volume` | `-v`  | `""`    | Volume name (skips interactive prompt)                   |
| `--bind`   |       | `false` | Take over container lifecycle (recreate with bind mount) |

## Examples

### Interactive Init

```bash theme={null}
graft init my-postgres
```

Prompts you to select which volume contains the database data.

### With Explicit Volume

```bash theme={null}
graft init my-postgres --volume myapp_postgres_data
```

### With Bind Mount

```bash theme={null}
graft init my-postgres --bind
```

In bind mount mode, Graft takes full control of the container lifecycle. After init, the container uses a host bind mount instead of a Docker volume.

## Output

```text theme={null}
Initialising my-postgres...
Bridging volume myapp_postgres_data -> ~/.graft/my-postgres/branches/main...
Graft initialized. Project root: ~/.graft/my-postgres
Main branch size: 289.2M
Container is now bound to the host directory via a Docker bind mount (--bind mode).
Run 'graft commit -m "initial state"' to capture this as your first save point.
```

## Modes

| Mode     | Flag      | Container                      | Best For                       |
| -------- | --------- | ------------------------------ | ------------------------------ |
| Snapshot | (default) | Left on original Docker volume | Quick setup, manual management |
| Bind     | `--bind`  | Recreated with host bind mount | Full Graft-managed lifecycle   |

In snapshot mode, `graft commit` bridges from the Docker volume to the host. In bind mode, the container's data lives directly on the host and no bridging is needed.

## Exit Codes

| Code | Meaning                                                      |
| ---- | ------------------------------------------------------------ |
| `0`  | Initialized successfully                                     |
| `1`  | Error (container not found, no volumes, already initialized) |