Skip to main content
zo init <project> is the first command in the pipeline. It creates everything ZO needs to track a project, plus a delivery repo scaffold.

​
Synopsis

zo init PROJECT_NAME [OPTIONS]

​
What it does

1

Detects host environment

Calls zo.environment.detect_environment() to capture platform, Python version, GPU/CUDA details, Docker availability. Used to populate the plan’s ## Environment section and pick an appropriate Docker base image.
2

Resolves delivery repo path

Three modes: explicit --existing-repo PATH (overlay), explicit --scaffold-delivery PATH (new scaffold), or default (../<project>-delivery).
3

Writes ZO-side artifacts

memory/{project}/{STATE,DECISION_LOG,PRIORS}.md, targets/{project}.target.md, plans/{project}.md.
4

Writes delivery-side artifacts

.zo/{config.yaml, memory/, plans/} (portable project state), full src/, configs/, experiments/, reports/, notebooks/phase/, tests/, docker/ scaffold.
5

Picks Docker compose template

Platform-aware: GPU template on Linux+CUDA, CPU template on macOS / no-GPU Linux. The deploy.resources.devices: capabilities: [gpu] block is omitted on CPU to avoid docker compose up failures.

​
Modes

zo init my-project
Launches the Init Architect in a tmux pane. The agent:
  • Greets you with the brand banner
  • Asks 5–6 confirming questions (project location, delivery repo, base image, GPU host, data path, layout mode)
  • Inspects the target repo if it already exists (Glob, Read, Bash)
  • Runs zo init ... --no-tmux --dry-run to preview exactly what will be written
  • Asks you to approve before committing writes
  • Routes the actual file writes through zo init ... --no-tmux ... so the CLI is the single source of truth
Use this on first runs of a new project, or when adopting an existing repo where you’re not sure what layout mode to pick.

​
Layout modes

--layout-mode controls how the scaffold interacts with existing code:
Creates the full ZO layout: configs/, src/{data,model,engineering,inference,utils}/, data/{raw,processed}/, experiments/, reports/, notebooks/{,phase}/, tests/{unit,ml,fixtures}/, docker/.Best for: fresh projects, existing repos with no established code layout.

​
Options

OptionDefaultPurpose
--no-tmux(off)Disable conversational mode. Implies headless flag-driven init.
--dry-run(off)Preview writes without filesystem changes. Requires --no-tmux.
--reset(off)Delete ZO artifacts for this project. Requires --yes or typing the project name.
--yes, -y(off)Skip confirmation prompts. Used with --reset.
--branchmainGit branch on the delivery repo.
--existing-repo PATH(none)Apply ZO scaffold as overlay to an existing repo. Requires .git/.
--scaffold-delivery PATH(auto)Create scaffold at this absolute path. Default is ../<project>-delivery. Mutually exclusive with --existing-repo.
--base-image IMAGE(auto)Docker base image. Auto-detected via suggest_base_image(env).
--gpu-host HOST(auto)GPU host. local if running on the GPU machine, user@host:/path for remote.
--data-path PATH(auto)Path to data. Use host:/abs/path for remote-data flows.
--no-detect(off)Skip host environment auto-detection. Leaves the plan’s ## Environment as TODO.
--layout-mode MODEstandardstandard or adaptive. Adaptive requires --existing-repo.

​
Examples

zo init mnist-demo
Launches the Init Architect. Default delivery repo at ../mnist-demo-delivery.
zo init my-project --existing-repo ~/code/my-project --layout-mode adaptive
Adds only ZO meta-dirs. Init Architect customises STRUCTURE.md to your existing src/ layout.
zo init my-project --no-tmux \
  --branch feature/ml-pipeline \
  --base-image pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime \
  --gpu-host local \
  --data-path /mnt/data

zo init my-project --no-tmux --dry-run
Prints the file tree, target.md, plan.md Environment block. Re-run without --dry-run to commit.
zo init my-project --reset --yes
Wipes ZO artifacts. Delivery repo is preserved.

​
What gets written

After a successful zo init my-project: 
zero-operators/                                 # ZO repo
├── memory/my-project/
│   ├── STATE.md
│   ├── DECISION_LOG.md
│   ├── PRIORS.md
│   └── sessions/
├── targets/my-project.target.md
└── plans/my-project.md                         # with ## Environment populated

../my-project-delivery/                         # delivery repo (or --existing-repo)
├── .zo/
│   ├── config.yaml
│   ├── memory/                                 # mirror of ZO-side memory
│   └── plans/my-project.md                     # mirror of ZO-side plan
├── configs/{data,model,training,experiment}/
├── src/{data,model,engineering,inference,utils}/    # standard mode only
├── data/{raw,processed}/                       # standard mode only
├── experiments/
├── notebooks/{,phase}/
├── reports/{,figures}/
├── tests/{unit,ml,fixtures}/
├── docker/{Dockerfile,docker-compose.yml,.dockerignore}
├── README.md, STRUCTURE.md, pyproject.toml, .gitignore

​
Next

zo draft

Now that the skeleton exists, draft the plan.

The plan

What goes into plans/<project>.md.