# AGR & AGRX CLI Commands Reference

All CLI commands for `agr` and `agrx` with user expectations, actual behavior, and UV comparisons.

---

## AGR Commands

### agr add

```bash
agr add <REFERENCE> [--type TYPE] [--overwrite] [--global] [--workspace NAME]
```

**User Expectation:** "I want to install a Claude Code resource (skill, command, or agent) into my project."

**What Actually Happens:**
1. Parses reference (GitHub `username/name` or local path `./path/to/resource`)
2. Auto-detects resource type from structure (or uses `--type` if specified)
3. Downloads/copies resource to `.claude/{skills,commands,agents}/`
4. Adds entry to `agr.toml` dependencies section

**Expectation Match:** ✅ Yes — straightforward install with sensible defaults.

**UV Comparison:**
| | agr add | uv add |
|--|---------|--------|
| Adds to | `agr.toml` | `pyproject.toml` |
| Installs to | `.claude/` | `.venv/` |
| Source | GitHub repos, local paths | PyPI, Git URLs |
| Auto-detect | Resource type | Package metadata |

---

### agr init

```bash
agr init
```

**User Expectation:** "I want to set up agr in my project."

**What Actually Happens:**
1. Creates `agr.toml` if it doesn't exist
2. Creates `resources/` directory with subdirs: `skills/`, `commands/`, `agents/`, `packages/`

**Expectation Match:** ✅ Yes — minimal scaffolding, no magic.

**UV Comparison:**
| | agr init | uv init |
|--|----------|---------|
| Creates | `agr.toml`, `resources/` dirs | `pyproject.toml`, `src/`, etc. |
| Purpose | Resource authoring structure | Python project structure |

---

### agr init skill

```bash
agr init skill <NAME> [--path PATH] [--legacy]
```

**User Expectation:** "I want to create a new skill with the correct structure."

**What Actually Happens:**
1. Creates directory at `resources/skills/<name>/` (or `--path`)
2. Generates `SKILL.md` template file inside

**Expectation Match:** ✅ Yes — creates minimal scaffold ready for editing.

**UV Comparison:** No direct equivalent. Closest is `uv init --lib` for creating a library, but skills encode AI behavior, not Python code.

---

### agr init command

```bash
agr init command <NAME> [--path PATH] [--legacy]
```

**User Expectation:** "I want to create a new slash command."

**What Actually Happens:**
1. Creates markdown file at `resources/commands/<name>.md` (or `--path`)
2. File contains template structure for command definition

**Expectation Match:** ✅ Yes — single file, ready to edit.

**UV Comparison:** Closest is adding a script entry to `[project.scripts]`, but commands are prompt templates, not Python entry points.

---

### agr init agent

```bash
agr init agent <NAME> [--path PATH] [--legacy]
```

**User Expectation:** "I want to create a new sub-agent definition."

**What Actually Happens:**
1. Creates markdown file at `resources/agents/<name>.md` (or `--path`)
2. File contains template for agent persona/behavior

**Expectation Match:** ✅ Yes — single file scaffold.

**UV Comparison:** No equivalent. Agents define autonomous AI behavior — a concept that doesn't exist in Python package management.

---

### agr init package

```bash
agr init package <NAME> [--path PATH]
```

**User Expectation:** "I want to create a package that bundles multiple resources."

**What Actually Happens:**
1. Creates directory at `resources/packages/<name>/`
2. Creates subdirs: `skills/`, `commands/`, `agents/`

**Expectation Match:** ✅ Yes — empty container ready to fill.

**UV Comparison:** Similar to creating a workspace or monorepo structure. Packages group related resources for collective installation.

---

### agr list

```bash
agr list [--format FORMAT] [--local] [--remote] [--global]
```

**User Expectation:** "I want to see what resources are declared and whether they're installed."

**What Actually Happens:**
1. Reads `agr.toml` dependencies
2. Checks `.claude/` for actual installation status
3. Displays table with: source (local/remote), type, name, installed status

**Expectation Match:** ✅ Yes — shows declared vs. installed state clearly.

**UV Comparison:**
| | agr list | uv pip list |
|--|----------|-------------|
| Shows | Dependencies from agr.toml + install status | Installed packages |
| Formats | table, simple, json | text, json |
| Filters | `--local`, `--remote` | type filters |

---

### agr remove

```bash
agr remove <NAME_OR_PATH> [--type TYPE] [--global]
```

**User Expectation:** "I want to uninstall a resource."

**What Actually Happens:**
1. Identifies resource by name or path
2. Removes from `.claude/` directory
3. Removes entry from `agr.toml`

**Expectation Match:** ✅ Yes — clean removal from both locations.

**UV Comparison:**
| | agr remove | uv remove |
|--|------------|-----------|
| Updates | `agr.toml` + `.claude/` | `pyproject.toml` + `uv.lock` |
| By name | Yes | Yes |
| By path | Yes | No |

---

### agr sync

```bash
agr sync [--global] [--prune] [--local] [--remote]
```

**User Expectation:** "I want my installed resources to match what's declared in agr.toml."

**What Actually Happens:**
1. Reads dependencies from `agr.toml`
2. Installs missing resources (downloads remote, copies local)
3. With `--prune`: removes resources in `.claude/` not listed in `agr.toml`

**Expectation Match:** ✅ Yes — declarative sync like you'd expect.

**UV Comparison:**
| | agr sync | uv sync |
|--|----------|---------|
| Source of truth | `agr.toml` | `uv.lock` |
| Prune behavior | Opt-in (`--prune`) | Default |
| Partial sync | `--local`, `--remote` | No |
| Deterministic | No (fetches latest) | Yes (locked versions) |

**Gap:** agr lacks lock file — `agr sync` fetches latest from source, not pinned versions.

---

## AGRX Commands

### agrx

```bash
agrx <REFERENCE> [PROMPT] [--type TYPE] [--interactive] [--global]
```

**User Expectation:** "I want to run a skill/command once without permanently installing it."

**What Actually Happens:**
1. Downloads resource to temporary location (prefixed `_agrx_`)
2. Invokes Claude CLI with the resource
3. Cleans up temporary files after execution
4. With `--interactive`: opens Claude session instead of one-shot

**Expectation Match:** ✅ Yes — try-before-you-buy workflow works as expected.

**UV Comparison:**
| | agrx | uvx |
|--|------|-----|
| Purpose | Run AI resource temporarily | Run Python tool temporarily |
| Cleanup | Yes | Yes (isolated env) |
| Interactive | `--interactive` flag | N/A |
| Source | GitHub | PyPI |

---

## Summary Table

| Command | Job To Be Done | Matches Expectation |
|---------|----------------|---------------------|
| `agr add` | Install a resource | ✅ Yes |
| `agr init` | Set up agr in project | ✅ Yes |
| `agr init skill` | Scaffold a skill | ✅ Yes |
| `agr init command` | Scaffold a command | ✅ Yes |
| `agr init agent` | Scaffold an agent | ✅ Yes |
| `agr init package` | Scaffold a package | ✅ Yes |
| `agr list` | See declared/installed resources | ✅ Yes |
| `agr remove` | Uninstall a resource | ✅ Yes |
| `agr sync` | Match installed to declared | ✅ Yes |
| `agrx` | Run without installing | ✅ Yes |

---

## UV Comparison Summary

**Direct Parallels:**
- `agr add` ↔ `uv add` — add dependency
- `agr remove` ↔ `uv remove` — remove dependency
- `agr sync` ↔ `uv sync` — sync installed state
- `agr init` ↔ `uv init` — initialize project
- `agr list` ↔ `uv pip list` — show dependencies
- `agrx` ↔ `uvx` — run without installing

**Key Differences:**
| Aspect | AGR | UV |
|--------|-----|-----|
| Domain | AI enhancement resources | Python packages |
| Lock file | None (fetches latest) | `uv.lock` (deterministic) |
| Versioning | Implicit (latest from source) | Explicit (pinned versions) |
| Resources | Skills, commands, agents | Libraries, tools |

**What AGR lacks vs UV:**
- Lock file for reproducible installs
- Version constraints (`>=1.0`, `~=2.3`)
- Dependency resolution/conflict detection

**What AGR has that UV doesn't:**
- AI-specific resource types (skills, agents)
- Natural language invocation model
- `--interactive` mode for AI sessions
