> ## Documentation Index > Fetch the complete documentation index at: https://docs.stratalint.com/llms.txt > Use this file to discover all available pages before exploring further. # strata init > Guided setup: detect your repository layout, write a starting configuration, measure current drift, and install agent skill files. `strata init` sets up Strata in a repository. It detects your layout, writes a `strata.toml` matched to how much code you already have, runs an initial check to show the current drift, and offers to install [agent skill files](/cli/skills). It never guesses silently: every detected path shows where it came from, and nothing is written until you confirm (or pass `--yes`). ```bash theme={null} strata init [--yes] [--root PATH ...] [--tests PATH ...] [--tooling PATH ...] [--full | --gradual] [--skills | --no-skills] [--name NAME] ``` ## What it does 1. **Detects your layout.** Package roots come from `pyproject.toml` metadata (hatch, setuptools, poetry, flit, uv workspaces, the project name), ruff's `src` setting, and a directory scan. Test paths come from pytest `testpaths` and `tests`/`test` directories; tooling from `scripts`, `tools`, `bin`, and `tasks` directories with Python files. 2. **Picks a starting ruleset.** An existing codebase starts [gradual](/adoption): `select = ["SFL", "SFH", "SFA", "SFN"]`. An empty repository gets the full `select = ["SF"]` and a scaffolded `src//` package plus `tests/`. 3. **Writes `strata.toml`** and updates your `.gitignore` to cover Strata's [cache directory](/cli/check#caching). 4. **Measures current drift** by running the starting ruleset once and printing per-family fault counts. 5. **Installs agent skill files** (`.claude/`, `.opencode/`, `.agents/`) unless you decline; see [`strata skills`](/cli/skills). ## Options | Option | Description | | -------------------------- | --------------------------------------------------------------------------------------------- | | `--yes` | Accept every detected choice; required when no terminal is attached. | | `--root PATH` | Use these package roots instead of the detected ones. Repeatable. | | `--tests PATH` | Use these test paths. Repeatable. | | `--tooling PATH` | Use these tooling paths. Repeatable. | | `--full` | Start with the full ruleset (`select = ["SF"]`) regardless of detection. | | `--gradual` | Start with the gradual ruleset regardless of detection. | | `--skills` / `--no-skills` | Install or skip agent skill files without prompting. | | `--name NAME` | Package name for an empty-repository scaffold. Only valid when no Python package is detected. | `--full` and `--gradual` are mutually exclusive, as are `--skills` and `--no-skills`. `--root`, `--tests`, and `--tooling` only apply when a codebase is detected; `--name` only applies when none is. ## An existing repository On a repository with code, `strata init` shows what it detected and why, then confirms before writing: ```text theme={null} --> Detecting project layout roots src/acme pyproject: hatch packages tests tests/ directory scan tooling none detected Accept? [Y/n/e] e = edit paths --> Existing codebase - 1,204 Python files Starting with the gradual ruleset: SFL, SFH, SFA, SFN Wrote strata.toml --> Measuring current drift SFA annotations 3,411 SFL layers 212 SFH hygiene 540 SFN naming 2 Found 4,165 faults across 310 files against the starting ruleset. See docs.stratalint.com/adoption for rolling out gradually. --> Install agent skill files? [Y/n] Updated .opencode/skills/strata/SKILL.md Updated .claude/skills/strata/SKILL.md Updated .agents/skills/strata/SKILL.md --> Next strata check run anytime strata rule SFA001 inspect any code in the output ``` Answering `e` at the confirmation lets you edit the paths; `n` aborts without writing anything. When several package roots are detected, you pick which to include by number. The gradual starting point deliberately holds back the families that imply refactors (`SFR` roles, `SFS` shape, `SFT` tests). Widen `select` as you go; see [Adopting Strata](/adoption). ## An empty repository With no Python code detected, `strata init` scaffolds a fresh layout instead. It asks for a package name (or derives it from the directory name, or takes `--name`), then starts fully enforced from the first commit. With `--yes --name Sample-App --no-skills`: ```text theme={null} --> Empty repository Created src/sample_app/__init__.py Created tests/ Wrote strata.toml --> Found 0 faults --> Agent skill files - no Run strata skills update when you are ready. --> Next strata check run anytime strata rule SFA001 inspect any code in the output ``` ## Gitignore handling Strata's result cache lives under `.strata/`, which should not be committed. * If a root `.gitignore` exists and does not already cover the cache path, `strata init` appends a `.strata/` entry to it. * An empty repository with no `.gitignore` gets one created from the standard GitHub Python template, plus the `.strata/` entry. * An existing repository with no `.gitignore` gets one containing just the `.strata/` entry. ## Rerunning is safe If the directory already has a `strata.toml` or a `[tool.strata]` table, `strata init` changes nothing and exits `0`: ```text theme={null} Strata configuration already exists: /path/to/repo/strata.toml (nothing to do) ``` If a **parent** directory's configuration would apply here instead, init refuses with an error rather than shadowing it. All writes are transactional: on any failure, files created during the run are rolled back. ## Non-interactive use Prompts require a terminal. In CI or scripts, pass `--yes` (or make every choice explicit with flags); otherwise init fails: ```text theme={null} Interactive initialization requires a TTY; use --yes or explicit options. ``` ```bash theme={null} strata init --yes --no-skills ``` ## Exit codes | Code | Meaning | | ---- | ---------------------------------------------------------------------------- | | `0` | Configuration written, or a local configuration already exists. | | `2` | Detection, validation, or write failure; declined confirmation; missing TTY. | ## Related The manual version of what init automates. Growing from the gradual ruleset to full enforcement. Every key in the file init writes. The agent guidance init offers to install.