---
title: CLI Bootstrap
description: 'Foundational setup via oat init for canonical directories, provider adoption, and configuration.'
---

# CLI Bootstrap

This page covers foundational CLI setup commands that prepare OAT structures and configuration before provider sync or tool-pack workflows.

## Quick Look

- What it does: explains the initial `oat init` setup flow and the optional guided setup path that configures packs, local paths, documentation metadata, and provider sync.
- When to use it: when you are first introducing OAT into a repo or need to re-run the guided setup path on an existing checkout.
- Primary commands: `oat init`, `oat init --setup`, `oat init --scope project`

## `oat init`

Purpose:

- Bootstrap canonical OAT directories for a scope
- Detect and optionally adopt provider strays
- Initialize sync configuration/manifest state
- Optionally install drift warning hooks
- Run guided setup to configure tool packs, local paths, documentation metadata, and provider sync in one session

Key behavior:

- Idempotent initialization
- Interactive adoption in TTY mode
- JSON/non-TTY contract support
- Establishes the base structure used by `oat status`, `oat sync`, `oat init tools`, and `oat doctor`
- For project scope, creates canonical `.agents/skills/`, `.agents/agents/`, and `.agents/rules/` directories

### Guided setup

After core initialization completes, `oat init` can enter an interactive guided setup flow that walks through common post-init configuration in a single session.

**Entry paths:**

- **`--setup` flag** — `oat init --setup` enters guided setup directly on any repo (new or existing).
- **Fresh init** — when `.oat/` did not exist before init, the user is automatically prompted to enter guided setup. No flag needed.

**Steps (each independently skippable):**

1. **Tool packs** — install OAT tool packs. The core pack (diagnostics, passive docs access) is checked by default and always installs at user scope. Guided setup asks whether to customize per-pack scope:
   - choose **Yes** to run the per-pack scope selector for user-eligible packs (`ideas`, `docs`, `utility`, `research`, `brainstorm`)
   - choose **No** to apply additive per-pack defaults without extra scope prompts
   - project-only packs such as `workflows` and `project-management` remain project-scoped
2. **Local paths** — multi-select from default gitignored artifact paths (analysis, PR, reviews, ideas). Pre-existing paths are pre-checked; only new paths are added.
3. **Documentation** — detect or enter docs metadata for the repo when documentation exists.
4. **Provider sync** — sync provider project views via `oat sync --scope project`.
5. **Summary** — reports what was configured: active providers, tool packs status, local paths added/existing, and provider sync status. Includes suggested next steps.

Hook install note:

- The optional OAT pre-commit hook installs into Git's active hook directory.
- If a repo uses a managed hook folder such as `.githooks/`, that path must already be configured in Git, or OAT must configure it during the prompt flow before hook install.

**Non-interactive mode:** Fresh-init guided setup offers are interactive-only. If `--setup` is passed in non-interactive mode (`--json`, piped input, non-TTY, or `OAT_NON_INTERACTIVE=1`), guided setup does not prompt: tool packs use additive defaults, local-path and documentation prompts are skipped unless already configured, and provider sync is skipped unless separately requested.

```bash
# Explicit guided setup on an existing repo
oat init --setup --scope project

# Fresh init — guided setup is offered automatically
oat init --scope project
```

Related commands:

- `oat tools ...` (tool-pack install, update, remove, list, info): `tool-packs.md`
- `oat local ...`, `oat doctor`, and other utility commands: `config-and-local-state.md`
- `oat status` / `oat sync` (provider sync): `../provider-sync/index.md`
