fracta init

Materialize a deployment scaffold (local, docker-compose, or k8s) into the current directory.

Materializes one of three deployment scaffolds (local, docker-compose, k8s) into the current directory. The first invocation drops a complete deployment tree in your project root; re-running with the same scaffold is idempotent. Switching scaffolds in an existing project is refused — see Switching modes below.

Only --scaffold local requires the directory to be a git repository (the local backend uses git worktrees to isolate agent runs). --scaffold k8s and --scaffold docker-compose run agents as Kubernetes Jobs or compose services and do not need a .git directory; you can fracta init --scaffold k8s in a fresh empty folder.

Initialize fracta in the current git repository by materializing a scaffold.

Examples:
  fracta init --scaffold local
  fracta init --scaffold docker-compose
  fracta init --scaffold k8s
  fracta init --scaffold k8s --source github:acme/fracta-scaffolds@v3.2.0
  fracta init --scaffold k8s --source ./local/templates
  fracta init --scaffold k8s --source https://example.com/scaffold-k8s.tar.gz \
    --source-checksum sha256:abc123...
  fracta init --scaffold local --force --yes

The first invocation drops a complete deployment tree into the operator's
repository. Re-running with --force overwrites existing files; without
--force, existing files are preserved.

Usage:
  fracta init [flags]

Flags:
      --scaffold string          Scaffold to lay down: local | docker-compose | k8s
      --source string            Override scaffold source (path, github:owner/repo@ref, or https://...)
      --source-checksum string   Optional sha256:<hex> for https:// sources
      --force                    Overwrite existing files
      --yes                      Skip confirmation prompt for --force
  -h, --help                     help for init

Scaffolds

--scaffold value	Use when	Produces
local	Single-machine development; agents run as host subprocesses	fracta.yaml (runtime.backend: local), .fracta/state.db, deployment/auth-helpers/
docker-compose	Local containerized stack: controlplane, gateway, postgres, falkordb, strategy-runner	fracta.yaml (thin client), deployment/docker-compose.yml, deployment/configs/, deployment/auth-helpers/
k8s	Kubernetes deployment; agents as Jobs or stream pods	fracta.yaml (runtime.backend: kubernetes with extra_volumes), deployment/k8s/manifests/, deployment/auth-helpers/

The local scaffold is the lightest; docker-compose and k8s scaffold a full service topology. See the per-mode guides:

• Local process
• Docker Compose
• Kubernetes

--source resolution

--source value	Resolves to
(unset)	The scaffold tree baked into your fracta binary (offline-by-default)
./relative/path or /abs/path	Local filesystem; expects <path>/<kind>/ to exist
github:owner/repo@ref	Codeload tarball from https://codeload.github.com/owner/repo/tar.gz/<ref>; expects <repo>/<kind>/
https://...tar.gz	Raw HTTPS tarball; expects <kind>/ at archive root

Tarball downloads are capped at 50 MB. HTTPS sources accept an optional --source-checksum sha256:<hex> for integrity verification — without it, init prints a warning and proceeds.

GitHub refs that don’t look like commit SHAs (anything not matching [0-9a-f]{7,}) emit a reproducibility warning to stderr — pin to commit SHAs or release tags for CI/CD.

What gets written

The walker materializes every file in the chosen scaffold tree, skipping existing files by default (so re-running fracta init doesn’t clobber operator edits). Files under any auth-helpers/ directory are always written with mode 0755; everything else preserves the source-reported mode or defaults to 0644.

fracta init also:

• Verifies the directory is a git repo only for --scaffold local (the local backend uses worktrees). Compose and k8s scaffolds skip this check; they run agents as services / Jobs, so .git is irrelevant.
• Checks scaffold-specific dependencies via prereq.EnsureDepsFor(kind): local needs git; docker-compose needs docker + the docker compose plugin; k8s needs kubectl (warns if no current kube-context, doesn’t fail).
• Initializes .fracta/state.db (SQLite) for local scaffolds only. Compose and k8s use postgres-backed state in their deployed services.
• Appends .fracta/ and .worktrees/ to .gitignore if not already present.

Switching modes

A project that’s already been scaffolded as one mode cannot be re-initialized as another. Spec-42 ships single-mode-per-project: the fracta.yaml, deployment/ tree, and embedded controlplane configs are mode-coupled, so a mixed scaffold would produce a tree where the manifests, configs, and top-level config disagree about what’s running.

If you try to switch:

$ fracta init --scaffold k8s
Error: this project is already scaffolded as local; cannot re-init as k8s
without losing customizations.

Resolution paths:

• Switch destructively: rm -rf deployment/ fracta.yaml .fracta/ && fracta init --scaffold k8s. Loses any operator edits.
• Re-run idempotently: fracta init --scaffold local against an existing local project skips existing files (0 written, N skipped) and refreshes anything missing.
• Multi-mode requirements: see the Switching modes section of the deployment overview for separate-repo and separate-worktree patterns.

Conflict policy and --force

Default	--force
Existing files are preserved (SkipExisting)	Existing files are overwritten (Overwrite)
Output reports N written, M skipped	Prompts [y/N] unless --yes is passed

--force is destructive and bypasses the mode-mismatch check above only if you rm -rf the relevant directories first. Force-overwriting an existing mode (e.g. --force --scaffold local on a local project) refreshes the template files in place — useful if you want to revert local edits.

Deprecated invocation

$ fracta init                   # no --scaffold flag
warning: 'fracta init' without --scaffold is deprecated; defaulting to
--scaffold local. This will be required in the next release.

The next major release will require --scaffold explicitly. Update scripts and documentation now.