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.

# 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