Convex-Dev/convex / .claude/skills/etch
etch
VerifiedInspect and maintain an Etch store — Convex's content-addressed database. Use when examining peer storage, diagnosing corruption, garbage collecting, or reading data by hash.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.9 KB |
SKILL.md
View on GitHub---
name: etch
description: Inspect and maintain an Etch store — Convex's content-addressed database. Use when examining peer storage, diagnosing corruption, garbage collecting, or reading data by hash.
allowed-tools: Bash
argument-hint: "[info|validate|dump|read|gc|migrate|repair] <etch-file>"
---
# Etch Store Operations
Etch is Convex's content-addressed store: values are keyed by hash, and a
single root hash reaches everything retained. Peers keep their state here.
Every subcommand takes the store file with `-e` / `--etch`:
```bash
java -jar convex.jar etch info -e /path/to/store.etch
```
## Inspecting
| Command | Purpose |
|---------|---------|
| `etch info` | Summary of the database — start here |
| `etch validate` | Check store integrity; `-m/--max-failures N` to bound reporting |
| `etch dump` | Export contents, CSV by default (value ID, type, memory size, encoding) |
| `etch read <hash>...` | Read specific values by hash; `--limit N` to cap output |
`info`, `dump` and `read` take `-o` / `--output-file` to write to a file rather
than the terminal — use it for `dump` on any real store, which is large.
Start a diagnosis with `info`, then `validate`. If validation reports failures,
capture the output before doing anything that mutates the store.
## Maintenance
These **modify or destroy data**. Confirm with the user, and make sure the peer
using the store is stopped first — operating on a live store risks corruption.
| Command | Effect |
|---------|--------|
| `etch gc` | Garbage collect the root tree. In-place by default; `--backup <file>` also retains the old store as a snapshot; `-o/--output <file>` collects into a fresh file instead |
| `etch clear` | Clears the root data. Does *not* collect garbage |
| `etch migrate --into <dest>` | Copy everything into another store; `--set-root` to set the destination root |
| `etch repair --into <dest>` | Reconstruct a fresh store from independently validated cells; source unchanged |
| `etch recover` | Adopt a completed GC cutover or roll an abandoned target back into the live store |
| `etch write -c/--cvx <source>` | Write a CVM value into the store |
To compact safely, prefer `gc -o <new-file>`: it collects into a fresh file and
leaves the source unmodified (note: status levels above PERSISTED, e.g.
ANNOUNCED, survive an in-place GC but not `--output`). Use `migrate` to copy
into another (possibly non-empty) store, or to change the store's format
version or encryption — see below.
For a combined snapshot and in-place collection, use
`gc --backup <snapshot-file>`. The collected store keeps the original live path;
the backup retains the pre-GC root and all old entries, including unreachable
data. It uses a hard link, so the backup must have a new filename on the same
filesystem with hard-link support. Existing backups are never overwritten.
The old disk space remains allocated until the snapshot is removed. Treat the
snapshot as read-only and use a separate copy for a backup on another filesystem.
`--backup` and `--output` are mutually exclusive. A backup left by an interrupted
command is not a confirmed snapshot; inspect the recovery state first.
On Windows use the same NTFS volume. Live writes after cutover use the collected
file, so they do not update the snapshot. The FFM backend releases mappings on
close; `MappedByteBuffer` mappings may defer installation at the live filename.
Etch follows its completion marker until a later open can finish installation;
`validate` and `repair` follow it too, so pass the store's own filename.
`repair` is the offline salvage path for a dirty or damaged source. It holds an
exclusive source lock, scans through physical EOF, and writes only canonical
CAD3 values whose stored content hashes verify. A complete result requires both
a fully persisted selected root and an exhaustive scan. If either condition
fails, the command reports failure but may leave a valid partial destination;
never replace the source with that output automatically.
Recovering an interrupted GC is what `recover` is for — reach for it before
concluding a store is lost.
## Encrypted Stores (Etch v3)
Etch format v3 supports encrypted stores — format spec in
`convex-core/docs/ETCHv3.md`.
**Opening** an encrypted store: any etch subcommand takes `--etch-key <alias>`
(keystore key alias or public-key prefix, password via `--etch-keypass`) or
`--etch-key-file <file>` (raw or hex 32-byte master key; `-` reads stdin).
With neither, the v3 header's public-key hint selects a keystore key
automatically, or an interactive session prompts for a hex key.
**Converting** a store: `etch migrate` (and `gc -o`) accept destination
options — `--into-version` (1, 2 or 3), `--into-cipher` (`none`,
`aes-256-ctr` or `chacha20`), `--into-key` / `--into-key-file` /
`--into-keypass` for the destination key, `--into-encrypt-index` (negatable)
and `--into-public-key-hint`. Encryption options require version 3; without a
destination key the resolved source key is reused.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |