# devspec Setup Guides

Use these guides when you are installing `devspec` into a target repository for the first time. They are written for developers who may be new to package managers or command-line setup.

## Which Setup Should I Use?

| Situation | Use this guide |
| --- | --- |
| You want the simplest one-time command. | [uv and uvx](uv.md) |
| Your team already uses Homebrew on macOS or Linux. | [Homebrew](homebrew.md) |
| Your Windows machine uses approved WinGet packages. | [WinGet](winget.md) |
| CLI setup paths are blocked. | [Manual copy](manual-copy.md) |

Install the package manager first when needed:

| Tool | Official install link |
| --- | --- |
| uv | [Install uv](https://docs.astral.sh/uv/getting-started/installation/) |
| Homebrew | [Install Homebrew](https://brew.sh/) |
| WinGet | [Install or use WinGet](https://learn.microsoft.com/windows/package-manager/winget/) |

Recommended default:

```text
uvx devspec init --target . --profile all --repo-state existing
```

## Command-Line Basics

Open a terminal from your target repository when possible. In VS Code, use **Terminal > New Terminal**.

The target repository is the project where you want to install `devspec`. Before running repository commands such as `devspec init`, go to that folder:

```text
cd D:\code\my-app
```

or on macOS/Linux:

```text
cd /Users/me/code/my-app
```

When a command uses `--target .`, the `.` means "the folder I am currently in."

## Standard Setup Flow

1. Install or run the `devspec` CLI.
2. Go to your target repository before running repository commands.
3. Install the framework files.
4. Validate the install.
5. Commit the copied files.

For one-off `uvx` setup, you can run the CLI directly from the target repository. For persistent package managers such as Homebrew or WinGet, install the CLI first, then run `devspec init`, `devspec doctor`, and `devspec sync` from the target repository.

If you are using `uvx`, prefix the `devspec` commands below with `uvx`, for example `uvx devspec doctor --target . --profile all`.

```text
devspec init --target . --profile all --repo-state existing
devspec doctor --target . --profile all
git status
git add .
git commit -m "Install devspec"
```

## What Each Argument Means

| Command or argument | Meaning | Beginner explanation | Common values |
| --- | --- | --- | --- |
| `version` | Print the devspec CLI version. | Use this to confirm the command runs. It does not change files. | `devspec version` |
| `init` | Install devspec files into a repo. | This is the action that copies devspec into your project. | `init` |
| `--target .` | Target repository path. | `.` means "the folder I am currently in." Use this after you `cd` into your repo. | `.`, `D:\code\my-app`, `/Users/me/code/my-app` |
| `--profile all` | Which adapter files to install or check. | `all` installs every supported AI tool integration. Use a smaller profile if your team uses only one tool. Required for `init` and `sync`; optional for `diff` and `doctor`, where omission uses the installed manifest profile or falls back to `all`. | `all`, `core`, `copilot`, `codex`, `cursor`, `claude`, `gemini`, `antigravity` |
| `--repo-state existing` | Whether the target repo already has code. | Required for `init`. Use `existing` for most real projects. Use `new` for a repo that has little or no code yet. | `existing`, `new` |
| `doctor` | Validate a devspec install. | Checks whether required devspec files are present and profiles look complete. | `doctor` |
| `diff` | Compare installed files with the packaged framework. | Shows installed/package version context, then checksum-based missing, modified, stale, protected, or profile-mismatched files. It does not write files. | `devspec diff --target .` |
| `sync` | Update framework-owned files. | Applies framework updates using checksum comparisons while preserving project-owned artifacts. Use `--dry-run` first. | `devspec sync --target . --profile all --dry-run` |
| `--dry-run` | Preview a sync. | Shows what `sync` would change without writing files. Only applies to `sync`. | `--dry-run` |
| `--force` | Overwrite reviewed framework-owned conflicts. | Applies to `init` and `sync`. Use only after reading the conflict output. Do not use casually. | `--force` |

## Common Examples

Check the installed CLI version:

```text
devspec version
```

Install into an existing repository:

```text
devspec init --target . --profile all --repo-state existing
```

Install into a new repository:

```text
devspec init --target . --profile all --repo-state new
```

Validate the install:

```text
devspec doctor --target . --profile all
```

Only GitHub Copilot:

```text
devspec init --target . --profile copilot --repo-state existing
```

Only Codex:

```text
devspec init --target . --profile codex --repo-state existing
```

Only Cursor:

```text
devspec init --target . --profile cursor --repo-state existing
```

Preview an upgrade:

```text
devspec diff --target .
devspec sync --target . --profile all --dry-run
```

Upgrade previews show the installed version from `devspec/.install-manifest.json`, the running package version, and a checksum-based file plan.

Apply an upgrade after reviewing the dry run:

```text
devspec sync --target . --profile all
```

Use an explicit Windows path instead of the current folder:

```text
devspec init --target D:\code\my-app --profile all --repo-state existing
```

Use an explicit macOS/Linux path instead of the current folder:

```text
devspec init --target /Users/me/code/my-app --profile all --repo-state existing
```

## What Success Looks Like

After setup, your target repository should include:

```text
devspec/
.github/prompts/
.github/agents/
AGENTS.md
```

If you installed `--profile all`, it should also include adapter folders such as `.claude/`, `.cursor/`, `.gemini/`, and `.agents/`.

Setup does not copy `.github/workflows/`. Those CI/CD files belong to this framework repository, and target repositories should keep their own workflows.

## Troubleshooting

| Problem | What to try |
| --- | --- |
| The terminal says `devspec` is not found. | Use `uvx devspec ...`, or close and reopen the terminal after installing a persistent command. |
| You are not sure what folder you are in. | Run `pwd` on macOS/Linux or `Get-Location` in PowerShell. |
| You installed into the wrong folder. | Delete only the copied devspec files from that folder, then run the command again from the correct repo. |
| `devspec init` reports conflicts. | Read the conflict list. Use `--force` only after you know the files are framework-owned and safe to replace. |
| CLI setup downloads are blocked. | Use [manual copy](manual-copy.md). |