devrail-dev · matthew-on-git · Mar 10, 2026 · Mar 10, 2026
diff --git a/content/docs/getting-started/_index.md b/content/docs/getting-started/_index.md
@@ -2,10 +2,28 @@
 title: "Getting Started"
 linkTitle: "Getting Started"
 weight: 10
-description: "Quick start guides for creating new DevRail projects and retrofitting existing repositories."
+description: "Get up and running with DevRail in minutes using devrail init."
 ---
 
-Get up and running with DevRail in minutes. Whether you are starting a brand-new project or adding DevRail standards to an existing repository, the process is straightforward.
+Get up and running with DevRail in minutes. The `devrail init` script generates all DevRail configuration files in your project directory with a single command.
+
+## Quick Start
+
+```bash
+# Run devrail init in your project directory
+curl -fsSL https://devrail.dev/init.sh | bash
+```
+
+This launches an interactive wizard that asks which languages you use, which CI platform you want (GitHub Actions or GitLab CI), and which DevRail layers to install. It generates all configuration files, handles existing file conflicts safely, and is idempotent (safe to re-run).
+
+For non-interactive use:
+
+```bash
+# Generate everything for a Python project with GitHub Actions
+curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages python --ci github --yes
+```
+
+See the [CLI Reference](/docs/getting-started/cli-reference/) for all options.
 
 ## Prerequisites
 
@@ -21,14 +39,15 @@ All other tools (linters, formatters, security scanners, test runners) are pre-i
 
 ## Choose Your Path
 
-- **[New Project](/docs/getting-started/new-project/)** -- Start a new repository from a DevRail template. All configuration files are pre-set.
+- **[New Project](/docs/getting-started/new-project/)** -- Start a new repository with `devrail init` or from a template.
 - **[Retrofit Existing Project](/docs/getting-started/retrofit/)** -- Add DevRail standards to a repository you already have.
 - **[Working with AI Agents](/docs/getting-started/agents/)** -- Get AI coding agents to follow DevRail standards in your projects.
+- **[CLI Reference](/docs/getting-started/cli-reference/)** -- Full `devrail init` command reference.
 - **[Compliance Badge](/docs/getting-started/badge/)** -- Add a DevRail compliance badge to your README.
 
 ## Verify Your Setup
 
-After setting up DevRail (either path), verify everything works by running:
+After setting up DevRail (any path), verify everything works by running:
 
 ```bash
 # Run all DevRail checks (linting, formatting, security, tests)

diff --git a/content/docs/getting-started/cli-reference.md b/content/docs/getting-started/cli-reference.md
@@ -0,0 +1,172 @@
+---
+title: "CLI Reference"
+linkTitle: "CLI Reference"
+weight: 25
+description: "Complete reference for the devrail init command."
+---
+
+## Installation
+
+`devrail init` is a single shell script. No package manager is required — run it directly with `curl`:
+
+```bash
+curl -fsSL https://devrail.dev/init.sh | bash
+```
+
+Or download it for repeated use:
+
+```bash
+curl -fsSL https://devrail.dev/init.sh -o devrail-init.sh
+chmod +x devrail-init.sh
+./devrail-init.sh [options]
+```
+
+## Synopsis
+
+```
+devrail init [options]
+```
+
+When run without options, the script launches an interactive wizard that prompts for languages, CI platform, and which adoption layers to install.
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--languages <list>` | Comma-separated list of languages (e.g., `python,bash,go`) |
+| `--ci <platform>` | CI platform: `github`, `gitlab`, or `none` |
+| `--all` | Install all 4 layers (agent files, pre-commit, Makefile, CI) |
+| `--agents-only` | Install only Layer 1 (agent instruction files) |
+| `--yes` | Non-interactive mode; skip existing files without prompting |
+| `--force` | Overwrite existing files without prompting |
+| `--dry-run` | Show what would be generated without writing any files |
+| `--version` | Print the DevRail version and exit |
+| `--help` | Print usage information and exit |
+
+## Supported Languages
+
+The `--languages` flag accepts any combination of the following:
+
+| Language | Pre-commit Hooks | Makefile Targets |
+|---|---|---|
+| `python` | ruff (lint + format) | ruff check, ruff format, pytest |
+| `bash` | shellcheck, shfmt | shellcheck, shfmt |
+| `terraform` | terraform_fmt, terraform_validate, terraform_tflint, terragrunt_fmt | tflint, terraform fmt |
+| `ansible` | ansible-lint | ansible-lint |
+| `ruby` | rubocop | rubocop, brakeman, bundler-audit |
+| `go` | golangci-lint | golangci-lint, gofumpt, govulncheck |
+| `javascript` | eslint, prettier | eslint, prettier, tsc, npm audit |
+| `rust` | cargo-fmt, cargo-clippy | cargo fmt, cargo clippy, cargo audit |
+
+## Adoption Layers
+
+`devrail init` uses a 4-layer progressive adoption model. In interactive mode, you choose which layers to install. In non-interactive mode, use `--all` for everything or `--agents-only` for just Layer 1.
+
+### Layer 1: Agent Instruction Files
+
+Files that tell AI coding agents (Claude Code, Cursor, OpenCode) how to work in your project.
+
+| File | Purpose |
+|---|---|
+| `CLAUDE.md` | Claude Code agent instructions |
+| `AGENTS.md` | Generic agent instructions |
+| `.cursorrules` | Cursor agent instructions |
+| `.opencode/agents.yaml` | OpenCode agent instructions |
+
+### Layer 2: Pre-commit Hooks
+
+Language-aware `.pre-commit-config.yaml` with hooks for your declared languages, plus conventional commits and gitleaks secret detection.
+
+### Layer 3: Makefile + Container
+
+| File | Purpose |
+|---|---|
+| `Makefile` | Two-layer delegation pattern (host → Docker → container) |
+| `DEVELOPMENT.md` | Canonical development standards reference |
+| `.editorconfig` | Editor formatting rules |
+| `.gitignore` | Standard ignore patterns (appended if exists) |
+| `.gitleaksignore` | Gitleaks allowlist |
+| `.devrail.yml` | Language declaration and project settings |
+
+### Layer 4: CI Pipelines
+
+**GitHub Actions** generates 6 workflow files:
+
+- `.github/workflows/lint.yml`
+- `.github/workflows/format.yml`
+- `.github/workflows/test.yml`
+- `.github/workflows/security.yml`
+- `.github/workflows/scan.yml`
+- `.github/workflows/docs.yml`
+
+Plus `.github/PULL_REQUEST_TEMPLATE.md` and `.github/CODEOWNERS`.
+
+**GitLab CI** generates:
+
+- `.gitlab-ci.yml` (single file with parallel check-stage jobs)
+- `.gitlab/merge_request_templates/default.md`
+- `.gitlab/CODEOWNERS`
+
+## Conflict Resolution
+
+When `devrail init` encounters an existing file:
+
+| Mode | Behavior |
+|---|---|
+| Interactive (default) | Prompts: **[s]kip**, **[o]verwrite**, or **[b]ackup + overwrite** |
+| `--yes` | Skips existing files (safe, preserves your files) |
+| `--force` | Overwrites existing files without prompting |
+
+### Makefile Merge Strategy
+
+| Scenario | Behavior |
+|---|---|
+| No existing Makefile | DevRail Makefile written normally |
+| Existing Makefile with DevRail markers | Updated in-place between markers |
+| Existing non-DevRail Makefile | Backed up to `Makefile.pre-devrail`, DevRail Makefile written, include guidance printed |
+
+### .gitignore Handling
+
+DevRail patterns are appended below a `# --- DevRail ---` marker. If the marker already exists, the append is skipped (idempotent).
+
+## `.devrail.yml` Configuration
+
+The script reads `.devrail.yml` if it exists, or creates one based on the `--languages` flag or interactive prompts.
+
+```yaml
+# .devrail.yml
+languages:
+  - python
+  - bash
+
+fail_fast: false
+log_format: json
+```
+
+## Examples
+
+```bash
+# Interactive mode — walks through all choices
+curl -fsSL https://devrail.dev/init.sh | bash
+
+# Greenfield Python project with GitHub Actions
+curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages python --ci github --yes
+
+# Add agent files only to any project
+curl -fsSL https://devrail.dev/init.sh | bash -s -- --agents-only --yes
+
+# Preview what would be generated (dry run)
+curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages go,rust --ci gitlab --dry-run
+
+# Multi-language project with GitLab CI
+curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages python,bash,terraform --ci gitlab --yes
+
+# Force overwrite all existing files
+curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages javascript --ci github --force
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `DEVRAIL_VERSION` | `v1` | Container image tag used in generated files |
diff --git a/content/docs/getting-started/new-project.md b/content/docs/getting-started/new-project.md
@@ -2,74 +2,57 @@
 title: "New Project"
 linkTitle: "New Project"
 weight: 10
-description: "Create a new DevRail-compliant project from a GitHub or GitLab template."
+description: "Create a new DevRail-compliant project using devrail init or a template."
 ---
 
-The fastest way to start a DevRail-compliant project is to create a repository from one of the official templates. All DevRail configuration files are included and pre-configured.
+## Recommended: `devrail init`
 
-## From GitHub Template
-
-### Step 1: Create the Repository
-
-Navigate to the [DevRail GitHub template](https://github.com/devrail-dev/github-repo-template) and click **"Use this template"** to create a new repository in your organization or personal account.
-
-Alternatively, use the GitHub CLI:
+The fastest way to start a new DevRail project is `devrail init`. Run it in an empty directory (or a freshly initialized git repo) and it generates all configuration files:
 
 ```bash
-# Create a new repository from the DevRail GitHub template
-gh repo create my-new-project --template devrail-dev/github-repo-template --public
-cd my-new-project
-```
-
-### Step 2: Configure Your Languages
-
-Edit `.devrail.yml` to declare which languages your project uses. The Makefile reads this file to determine which tools to run.
+mkdir my-new-project && cd my-new-project
+git init
 
-```yaml
-# .devrail.yml -- declare your project's languages
-languages:
-  - python
-  - bash
+# Interactive mode — prompts for languages and CI platform
+curl -fsSL https://devrail.dev/init.sh | bash
 
-fail_fast: false
-log_format: json
+# Or non-interactive — specify everything up front
+curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages python,bash --ci github --yes
 ```
 
-Supported languages: `python`, `bash`, `terraform`, `ansible`, `ruby`, `go`, `javascript`. List only the languages your project actually uses.
+This generates all DevRail files including the Makefile, `.devrail.yml`, pre-commit config, agent instruction files, CI workflows, and documentation. See the [CLI Reference](/docs/getting-started/cli-reference/) for all options.
 
-### Step 3: Install Pre-Commit Hooks
+After running `devrail init`:
 
 ```bash
 # Install git hooks for local enforcement
 make install-hooks
-```
 
-This sets up pre-commit hooks that run formatting checks and secret detection on every commit, plus a pre-push hook that runs `make check` before every push.
-
-### Step 4: Run Your First Check
-
-```bash
 # Run all DevRail checks
 make check
+
+# Make your first commit
+git add .
+git commit -m "feat: initialize project with DevRail standards"
 ```
 
-The first run pulls the dev-toolchain Docker image (~1 GB). Subsequent runs use the cached image and complete in under 5 minutes.
+## Alternative: From a Template
 
-### Step 5: Make Your First Commit
+You can also create a repository directly from one of the official templates. All DevRail configuration files are included and pre-configured.
 
-```bash
-# Stage all files
-git add .
+### From GitHub Template
 
-# Commit using conventional commit format
-git commit -m "feat: initialize project with DevRail standards"
-```
+Navigate to the [DevRail GitHub template](https://github.com/devrail-dev/github-repo-template) and click **"Use this template"** to create a new repository in your organization or personal account.
 
-The pre-commit hooks run automatically. If any check fails, fix the issue and commit again.
+Alternatively, use the GitHub CLI:
 
-## From GitLab Template
+```bash
+# Create a new repository from the DevRail GitHub template
+gh repo create my-new-project --template devrail-dev/github-repo-template --public
+cd my-new-project
+```
 
-### Step 1: Create the Project
+### From GitLab Template
 
 In GitLab, navigate to **New Project > Create from template > Custom** and select the DevRail GitLab template. Enter your project name and create the project.
 
@@ -87,23 +70,38 @@ git add .
 git commit -m "feat: initialize project with DevRail standards"
 ```
 
-### Step 2: Configure Your Languages
-
-Edit `.devrail.yml` just as described in the GitHub workflow above. The configuration file format is identical across platforms.
-
-### Step 3: Install Pre-Commit Hooks and Verify
+### After Creating from Template
 
 ```bash
+# Edit .devrail.yml to declare your project's languages
+# Configure your languages (see below)
+
 # Install git hooks
 make install-hooks
 
 # Run all DevRail checks
 make check
 ```
 
-## What Is Included in the Template
+## Configure Your Languages
+
+Edit `.devrail.yml` to declare which languages your project uses. The Makefile reads this file to determine which tools to run.
+
+```yaml
+# .devrail.yml -- declare your project's languages
+languages:
+  - python
+  - bash
+
+fail_fast: false
+log_format: json
+```
+
+Supported languages: `python`, `bash`, `terraform`, `ansible`, `ruby`, `go`, `javascript`, `rust`. List only the languages your project actually uses.
+
+## What Is Included
 
-Both templates ship with the following files:
+Whether you use `devrail init` or a template, you get the following files:
 
 | File | Purpose |
 |---|---|