Hop
a74f420307
Hop-State: A_06FN6TVSHKAXPT37Z25BN38 Hop-Proposal: R_06FN6TSP5HXV3S320BV6TN8 Hop-Task: T_06FN6RMF4VPW419BR2ZD9Q0 Hop-Attempt: AT_06FN6RMF4V18KAM05RFZ8ER
79 lines
2.7 KiB
Markdown
79 lines
2.7 KiB
Markdown
# CLI reference
|
|
|
|
Add `--json` anywhere in a command for machine-readable output. Successful
|
|
responses use this envelope:
|
|
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"data": {}
|
|
}
|
|
```
|
|
|
|
The JSON shape is an alpha contract and may evolve before the first tagged
|
|
release.
|
|
|
|
## Project and prompt lifecycle
|
|
|
|
| Command | Purpose |
|
|
|---|---|
|
|
| `hop init [path]` | Initialize Hop without moving the Git branch or index |
|
|
| `hop begin ...` | Interactive-agent entry point: initialize if needed, capture prompt, continue session |
|
|
| `hop prompt ...` | Controller-managed prompt or follow-up capture |
|
|
| `hop checkpoint STATE` | Freeze current attempt progress |
|
|
| `hop check STATE -- COMMAND...` | Validate an immutable checkpoint |
|
|
| `hop propose [--summary TEXT] STATE` | Freeze a candidate proposal |
|
|
| `hop land PROPOSAL [-- COMMAND...]` | Accept and synchronize the visible root |
|
|
| `hop refresh PROPOSAL` | Explicitly prepare/reuse conflict reconciliation |
|
|
|
|
`hop start` aliases `hop prompt`; `hop reconcile` aliases `hop refresh`.
|
|
|
|
## Controller and synchronization commands
|
|
|
|
| Command | Purpose |
|
|
|---|---|
|
|
| `hop accept PROPOSAL [-- COMMAND...]` | Accept internally without changing visible files |
|
|
| `hop sync` | Materialize the current accepted tree from a safe accepted ancestor |
|
|
| `hop export [--output PATH]` | Write immutable, repository-safe prompt records to `.hop/records/prompts/` |
|
|
| `hop push` | Retry publishing the current accepted commit to its inferred upstream |
|
|
| `hop undo` | Create a forward-only acceptance that restores the previous accepted tree |
|
|
| `hop doctor [--repair]` | Validate database/object/ref consistency |
|
|
|
|
## Inspection
|
|
|
|
| Command | Purpose |
|
|
|---|---|
|
|
| `hop status` | Accepted head, attempts, and visible-root status |
|
|
| `hop graph` | State graph |
|
|
| `hop state STATE` | One state and its provenance |
|
|
| `hop env STATE` | Shell exports for an attempt |
|
|
| `hop diff STATE` | Diff represented by a state |
|
|
| `hop history` | Accepted lineage |
|
|
| `hop version` | Installed version |
|
|
|
|
## Agent integration bundle
|
|
|
|
```bash
|
|
hop skill install [--path SKILLS_DIR] [--force]
|
|
hop skill print
|
|
```
|
|
|
|
Without `--path`, Hop installs the same Hop-managed skill files at
|
|
`~/.agents/skills/hop` and `${CODEX_HOME:-~/.codex}/skills/hop`. With `--path`,
|
|
it installs only to `SKILLS_DIR/hop`.
|
|
|
|
## Exit codes
|
|
|
|
| Code | Meaning |
|
|
|---:|---|
|
|
| `0` | Success |
|
|
| `1` | Git, SQLite, filesystem, or internal failure |
|
|
| `2` | Invalid usage |
|
|
| `20` | Merge conflict; reconciliation workspace was prepared |
|
|
| `21` | Attempt or accepted head changed during compare-and-swap |
|
|
| `22` | Validation command failed |
|
|
| `23` | Visible-root divergence or overwrite collision |
|
|
|
|
Exit `20` is a continuation signal for an agent, not a request for the user to
|
|
manually merge files.
|