# Scripts Reference

Management scripts for setup, updates, and health checks. All scripts live in `scripts/` and are idempotent — safe to re-run.

## Quick Reference

| Script                   | Purpose                                | When to use                 |
| ------------------------ | -------------------------------------- | --------------------------- |
| [`update.sh`](#updatesh) | Update config, pi, and packages        | Regular maintenance         |
| [`status.sh`](#statussh) | Show system health and config overview | Debugging, pre-flight check |
| [`sync.sh`](#syncsh)     | Push to github (squash, sanitized)     | After any commit batch      |

## `update.sh`

One-command update for everything: config, pi binary, and all packages.

### What it does

1. **Git pull** — pulls latest config from remote (auto-stashes local changes, restores after)
2. **`pi update`** — updates pi binary and all installed packages
3. **Reinstall packages** — ensures all community packages are installed
4. **Extension deps** — re-runs `npm install` in extensions directory

### Usage

```bash
~/.pi/agent/scripts/update.sh
```

### Git behavior

- Auto-stashes uncommitted changes before pulling
- Tries `--ff-only` first, falls back to `--rebase`
- Restores stash after update
- If conflicts occur during stash pop, they're reported for manual resolution

## `status.sh`

Health check that shows the full system overview.

### What it shows

| Section            | Details                                           |
| ------------------ | ------------------------------------------------- |
| **pi version**     | Installed version of pi                           |
| **config**         | Default model, provider, theme from settings.json |
| **endpoint**       | Name, URL, and reachability status                |
| **git**            | Remote URL, branch, dirty state, ahead/behind     |
| **packages**       | Version of each installed community package       |
| **authentication** | Configured providers from auth.json               |
| **disk usage**     | Total size of `~/.pi/agent` and `sessions/`       |

### Usage

```bash
~/.pi/agent/scripts/status.sh
```

Green values mean healthy, yellow indicates warnings (unreachable endpoint, dirty git state, behind remote).

## Troubleshooting

### Git conflicts during update

```bash
cd ~/.pi/agent
git status                 # See what's conflicted
git stash list             # Check for stashed changes
git stash pop              # Apply stash manually
# Resolve conflicts, then:
git add <files>
git commit -m "resolve conflicts"
```

### `pi` command not found

```bash
npm install -g @earendil-works/pi-coding-agent
```

### Package install failures

```bash
cd ~/.pi/agent/extensions && npm install
pi install npm:pi-mcp-adapter npm:pi-subagents npm:pi-lens # ...etc
```

## `sync.sh`

Push to github with a squashed, sanitized commit.

### What it does

1. Fetches `main` state from `github` remote
2. Pushes current branch
3. Builds a sanitized git tree via a temp index (strips `models.json`)
4. Creates a squash commit on top of `github/main` using `git commit-tree` — no branch switching, no working tree changes
5. Force-with-lease pushes to `github/main`

### Usage

```bash
scripts/sync.sh                          # auto-message from recent commits
scripts/sync.sh "feat: add X extension" # custom message
```
