agentspec-cli 0.1.0

package/README.md

@@ -0,0 +1,343 @@
+# @agentspec/cli
+
+The official CLI for [AgentSpec](https://agentspec.sh) — install, manage, and switch between AI agent configurations (configs, skills, rules, and specs) from the command line.
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @agentspec/cli
+
+# Or run without installing
+npx @agentspec/cli install <id>
+```
+
+**Requirements:** Node.js 18 or later.
+
+## Quick Start
+
+```bash
+# Browse and install a Claude Code config
+agentspec list configs --framework ClaudeCode
+agentspec install my-claude-config
+
+# Install a skill for Codex
+agentspec install my-skill --framework Codex
+
+# Activate a full spec (installs all configs + skills + rules at once)
+agentspec use my-team-spec
+
+# Check what's installed
+agentspec status
+
+# Update everything to the latest version
+agentspec update --all
+```
+
+## Commands
+
+### `agentspec install <id>`
+
+Install a config, skill, rule, or spec by ID or slug.
+
+```bash
+agentspec install <id|slug> [options]
+```
+
+| Option               | Description                                   |
+| -------------------- | --------------------------------------------- |
+| `--type <type>`      | Skip auto-detect: `config\|skill\|rule\|spec` |
+| `--framework <name>` | Target framework for skills (skips prompt)    |
+| `--file-type <type>` | Target file type for rules (skips prompt)     |
+| `--global`           | Install globally as a symlink                 |
+| `--project`          | Install to current project as a file copy     |
+| `--dry-run`          | Preview without writing any files             |
+
+**Scope behavior:**
+
+- **Project** (`--project`): Writes a real file copy to your project directory. The file can be edited and committed to git. After `agentspec update`, re-install to refresh the copy.
+- **Global** (`--global`): Creates a symlink from the standard tool location (e.g. `~/.claude/settings.json`) to `~/.agentspec/store/<slug>/content`. Updating the store automatically updates the symlinked file everywhere.
+- If the content type does not support global installation, defaults to `--project`.
+- If neither flag is set, you are prompted interactively.
+
+**Examples:**
+
+```bash
+# Install a config (prompts for scope)
+agentspec install my-claude-config
+
+# Install globally without prompt
+agentspec install my-claude-config --global
+
+# Install a skill for a specific framework
+agentspec install code-review-skill --framework ClaudeCode --project
+
+# Install a rule as a specific file type
+agentspec install no-todos-rule --file-type claude-md
+
+# Preview what would happen
+agentspec install my-team-spec --dry-run
+```
+
+---
+
+### `agentspec uninstall <id>`
+
+Remove an installed config, skill, or rule.
+
+```bash
+agentspec uninstall <id|slug> [options]
+```
+
+| Option      | Description                 |
+| ----------- | --------------------------- |
+| `--global`  | Uninstall from global scope |
+| `--project` | Uninstall from this project |
+
+For **global** installs: removes the symlink and restores the original file from backup (if one was saved).
+
+For **project** installs: prompts whether to `keep` the file (just stop tracking) or `delete` it from disk.
+
+```bash
+agentspec uninstall my-claude-config
+agentspec uninstall my-claude-config --global
+```
+
+---
+
+### `agentspec update [slug]`
+
+Update installed items to their latest version from agentspec.sh.
+
+```bash
+agentspec update [slug] [options]
+```
+
+| Option      | Description                                                  |
+| ----------- | ------------------------------------------------------------ |
+| `--all`     | Update all items in the store                                |
+| `--check`   | Only check for updates, do not apply                         |
+| `--force`   | Overwrite even if the local store copy was manually modified |
+| `--dry-run` | Preview without writing anything                             |
+
+Update detection uses SHA-256 content hashes. If your local store copy was manually edited, the update is skipped unless `--force` is passed.
+
+> **Note:** Global installs (symlinks) automatically reflect store updates. Project installs (file copies) need to be re-installed after an update.
+
+```bash
+# Check if any updates are available
+agentspec update --check
+
+# Update a single item
+agentspec update my-claude-config
+
+# Update everything, overwriting local edits
+agentspec update --all --force
+```
+
+---
+
+### `agentspec use <spec>`
+
+Activate a spec — installs all its configs, skills, and rules in one shot.
+
+```bash
+agentspec use <spec-id|spec-slug> [options]
+```
+
+| Option      | Description                          |
+| ----------- | ------------------------------------ |
+| `--global`  | Activate globally                    |
+| `--project` | Activate for this project only       |
+| `--none`    | Deactivate the currently active spec |
+| `--dry-run` | Preview without writing files        |
+
+Activating a new spec automatically deactivates the previously active one first. All items installed by the spec are tracked — `agentspec use --none` cleanly removes them all.
+
+```bash
+# Activate a spec for this project
+agentspec use my-team-spec --project
+
+# Activate globally
+agentspec use my-team-spec --global
+
+# Deactivate the current spec
+agentspec use --none
+```
+
+---
+
+### `agentspec status`
+
+Show currently installed items and the active spec.
+
+```bash
+agentspec status [options]
+```
+
+| Option     | Description                                               |
+| ---------- | --------------------------------------------------------- |
+| `--global` | Show global installation state                            |
+| `--store`  | List all items in the local store (`~/.agentspec/store/`) |
+
+```bash
+# Show what's installed in the current project
+agentspec status
+
+# Show globally installed items
+agentspec status --global
+
+# List everything in the local store
+agentspec status --store
+```
+
+---
+
+### `agentspec search <query>`
+
+Search for configs, skills, rules, specs, and plugins on agentspec.sh.
+
+```bash
+agentspec search <query> [options]
+```
+
+| Option          | Description                                                               |
+| --------------- | ------------------------------------------------------------------------- |
+| `--type <type>` | Filter by type: `all\|config\|skill\|rule\|spec\|plugin` (default: `all`) |
+| `--limit <n>`   | Max results (default: `10`, max: `50`)                                    |
+
+```bash
+agentspec search "code review"
+agentspec search "strict typescript" --type config
+agentspec search "refactoring" --type skill --limit 5
+```
+
+---
+
+### `agentspec list <type>`
+
+Browse configs, skills, rules, or specs on agentspec.sh.
+
+```bash
+agentspec list <configs|skills|rules|specs> [options]
+```
+
+| Option               | Description                                      |
+| -------------------- | ------------------------------------------------ |
+| `--sort <sort>`      | Sort: `hot\|new\|top\|installs` (default: `hot`) |
+| `--framework <name>` | Filter by framework                              |
+| `--file-type <type>` | Filter rules by file type                        |
+| `--limit <n>`        | Number of results (default: `20`, max: `100`)    |
+| `--offset <n>`       | Pagination offset (default: `0`)                 |
+
+```bash
+# List top Claude Code configs
+agentspec list configs --framework ClaudeCode --sort top
+
+# Latest skills for Codex
+agentspec list skills --framework Codex --sort new
+
+# Browse CLAUDE.md rules
+agentspec list rules --file-type claude-md
+
+# Next page
+agentspec list specs --limit 20 --offset 20
+```
+
+---
+
+### `agentspec info <id>`
+
+Show details for a config, skill, rule, spec, or plugin.
+
+```bash
+agentspec info <id|slug> [options]
+```
+
+| Option          | Description                                           |
+| --------------- | ----------------------------------------------------- |
+| `--type <type>` | Skip auto-detect: `config\|skill\|rule\|spec\|plugin` |
+
+Displays title, slug, author, vote count, install count, description, supported frameworks/file types, install paths, and a content preview.
+
+```bash
+agentspec info my-claude-config
+agentspec info abc123 --type skill
+```
+
+---
+
+## Global Store
+
+The CLI stores all content in `~/.agentspec/` (override with `$AGENTSPEC_HOME`):
+
+```
+~/.agentspec/
+├── global-state.json        # Active spec + globally installed items
+├── store/
+│   └── <slug>/
+│       ├── content          # Raw file content
+│       └── meta.json        # ID, type, title, framework, fetched date, content hash
+├── backups/                 # Originals replaced by global symlinks
+└── projects/
+    └── <project-hash>/
+        └── state.json       # Per-project active spec + installed items
+```
+
+Items are always saved to the store regardless of install scope. This means:
+
+- **Global symlinks** automatically pick up `agentspec update` changes.
+- **Project copies** need to be re-installed after an update.
+
+---
+
+## Supported Frameworks & Install Paths
+
+### Configs
+
+| Framework    | Project path            | Global path                        |
+| ------------ | ----------------------- | ---------------------------------- |
+| `ClaudeCode` | `.claude/settings.json` | `~/.claude/settings.json`          |
+| `Codex`      | `codex.toml`            | `~/.codex/codex.toml`              |
+| `OpenCode`   | `opencode.json`         | `~/.config/opencode/opencode.json` |
+
+### Skills
+
+| Framework    | Project directory   | Global directory      |
+| ------------ | ------------------- | --------------------- |
+| `ClaudeCode` | `.claude/skills/`   | `~/.claude/skills/`   |
+| `Codex`      | `.codex/skills/`    | `~/.codex/skills/`    |
+| `OpenCode`   | `.opencode/skills/` | `~/.opencode/skills/` |
+| `Windsurf`   | `.windsurf/skills/` | _(no global)_         |
+| `Universal`  | `skills/`           | _(no global)_         |
+
+### Rules
+
+Rules are always installed as project files (no global scope).
+
+| File Type              | Install Path                      | Agent                |
+| ---------------------- | --------------------------------- | -------------------- |
+| `claude-md`            | `CLAUDE.md`                       | Claude Code          |
+| `agents-md`            | `AGENTS.md`                       | Claude Code / Codex  |
+| `cursorrules`          | `.cursorrules`                    | Cursor               |
+| `cursor-rules`         | `.cursor/rules/<title>.md`        | Cursor (directory)   |
+| `copilot-instructions` | `.github/copilot-instructions.md` | GitHub Copilot       |
+| `windsurfrules`        | `.windsurfrules`                  | Windsurf             |
+| `windsurf-rules`       | `.windsurf/rules/<title>.md`      | Windsurf (directory) |
+| `clinerules`           | `.clinerules`                     | Cline                |
+| `gemini-md`            | `GEMINI.md`                       | Gemini               |
+
+---
+
+## Environment Variables
+
+| Variable            | Default                    | Description                                         |
+| ------------------- | -------------------------- | --------------------------------------------------- |
+| `AGENTSPEC_HOME`    | `~/.agentspec`             | Override the global store location                  |
+| `AGENTSPEC_API_URL` | `https://api.agentspec.sh` | Override the API base URL (useful for self-hosting) |
+
+---
+
+## License
+
+MIT