Skip to main content

​
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

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

FlagAliasDefaultDescription
--volume-v""Volume name (skips interactive prompt)
--bindfalseTake over container lifecycle (recreate with bind mount)

​
Examples

​
Interactive Init

graft init my-postgres
Prompts you to select which volume contains the database data.

​
With Explicit Volume

graft init my-postgres --volume myapp_postgres_data

​
With Bind Mount

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

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

ModeFlagContainerBest For
Snapshot(default)Left on original Docker volumeQuick setup, manual management
Bind--bindRecreated with host bind mountFull 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

CodeMeaning
0Initialized successfully
1Error (container not found, no volumes, already initialized)