# Celilo CLI Docs

Canonical user-facing docs live at https://celilo.computer/docs. This
file is the offline-readable summary for engineers working in the repo.

## Alerting

See [ALERTING.md](./ALERTING.md) — people, routes, escalation policies,
watching a module, and what to do when an alert arrives.

## System update runbook

Canonical: https://celilo.computer/docs/system-update

### Philosophy

`celilo system update` is the single command for bringing a deployment
back to "READY" — the audit-determined state where every drift category
is clean. It is built on three guarantees:

1. **Audit first.** `update` runs `system audit` as its first step and
   refuses to proceed if the verdict is `BLOCKED`. The audit is also
   exposed as a standalone read-only command (`system audit`) for use
   in cron, CI, or interactive checks.
2. **Backups before mutation.** Every module that runs through the
   update flow gets a fresh backup tagged with the run's `update_id`
   before any change is applied. `--no-backup` skips this and is the
   only way to opt out.
3. **Failures isolate to the dependency subtree.** The orchestrator
   walks modules in topological order. A failure on a provider skips
   only its transitive consumers — peers and unrelated modules continue.
   Consumers may also proceed if their declared `requires` version
   still satisfies the running provider (version-aware skip).

### Recommended sequence

```
celilo system audit            # cheap, read-only — run any time
celilo system update --dry-run # preview the plan
celilo system update           # do it
```

For a single module:

```
celilo system update --module <id>
```

For an audit that returns `BLOCKED` on a destructive Terraform plan:

```
celilo system update --allow-destructive   # only after reviewing the plan
```

### Rollback

Pre-update backups are tagged with the `update_id` printed in the
`system update` output. To roll back a single module:

```
celilo backup list --module <id>
celilo backup restore <backup-id>
```

System-state snapshots (the celilo SQLite DB) are taken before the
first module mutation in a run; restore them via the same flow with
the system-scoped backup id.

### FAQ

**Q. Why did `system update` skip module X?**
Likely one of:
- `system audit` reported no drift for X (already at latest).
- A provider that X depends on failed earlier in the run, AND X's
  `requires` declares a version newer than the still-running provider.
  Output line `skipReason` makes the cause explicit.
- `--module <id>` was passed and X wasn't the named module.

**Q. The audit says `capability_abi: BLOCKED` — what now?**
A module's manifest declares a capability version that the running
`@celilo/capabilities` SDK no longer supports (or vice versa). Either
upgrade the framework (`bun update -g @celilo/cli` then re-run `system
update`) or rebuild the module against the new SDK and republish.
`CAPABILITY_CONTRACT_VERSIONS` in `packages/capabilities/src/capability-contract.ts`
is the source of truth.

### Troubleshooting

**Schema migrations fail on update.** `system audit` checks pending
migrations as part of `schema` drift. If a migration is failing on
your DB, `bun run drizzle-kit migrate` from `apps/celilo/` will print
the error directly.

**Backups storage is full.** Pre-update backups live in their own
retention pool tagged with the `update_id`. They are pruned by
`backup retention` policy independently from regular backups. Inspect
with `celilo backup list --type pre-update`.

## Related

- Design doc: `apps/celilo/designs/CELILO_UPDATE.md`
- Audit categories: `apps/celilo/src/services/audit/`
- Orchestrator: `apps/celilo/src/services/update/`