CLI reference

Add --json anywhere in a command for machine-readable output. Successful responses use this envelope:

{
  "ok": true,
  "data": {}
}

The v1.1.4 JSON envelope is stable for automation. Newer compatible releases may add fields, so consumers should ignore keys they do not recognize.

Project and prompt lifecycle

hop start aliases hop prompt; hop reconcile aliases hop refresh.

Controller and synchronization commands

Legacy Gitea authentication

These commands support existing private Gitea installations; they are not required for GitHub, GitLab, generic Git servers, or Hop's local workflow. Authentication is global to the device, not stored in a repository. The selected forge is discovered through FORGE_URL/hop/api/v1/auth/config and must advertise Gitea's all scope. Prompt uploads are matched to the repository's configured Git remote; the CLI never submits a user ID supplied by local project data. The same OAuth grant authenticates Hop's private same-forge Git fetch and push operations.

Inspection

hop status is read-only with respect to refs, HEAD, the real index, and the working tree. Its JSON separates the accepted tree projected into the visible root from the active branch and index. A safe landing normally makes ordinary Git status clean. If git.projection_only_changes=true remains, raw Git dirtiness is projection output, not uncommitted user work. Run hop sync-git for an idempotent repair attempt, exact blocking reason, and safe next action. git.user_worktree_paths and git.user_index_paths contain filesystem/index differences, while accepted_provenance reports whether the accepted transition's exact-tree authorization proof is verified, legacy_unverified, or invalid.

hop sync-git holds Hop's acceptance lock, revalidates the visible-tree and durable-state proofs, rejects detached/wrong branches, local commits, divergence, staged or visible changes, Git operations, and lock files, then uses a compare-and-swap fast-forward and atomic index replacement. It never materializes files, force-updates a ref, or invokes reset --hard. It also runs automatically after normal landing/materialization and after prompt capture in hop begin so safely repairable older projections self-heal. Publication may still be pending or failed: the local branch remains clean and ordinary Git reports its truthful relationship to the upstream.

Publication is not_configured, pending, current, failed, or unknown for a pre-migration accepted state. Failures retain a sanitized error category, timestamp, retryability, target remote/ref, and any authoritative remote tip. hop push performs a fresh remote comparison, rejects divergence without force, and changes the durable state to current after success.

CLI updates

hop update
hop update --check
hop update --version v1.1.4

Hop downloads the matching release archive and checksums.txt, verifies its SHA-256 checksum and embedded version, atomically replaces a standalone install, and refreshes all default skill bundles. A downgrade or same-version reinstall requires --force. On Windows, a verified helper finishes replacement after the running process exits. HOP_RELEASE_API_URL, HOP_RELEASE_URL, and HOP_REPOSITORY select another release source; the equivalent CLI flags are --api-url, --download-url, and --repository. --base-url remains a deprecated Gitea bridge for older private distributions.

Package-manager installations remain owned by that package manager and should use its update command instead of replacing files inside its package directory.

Agent integration bundle

hop skill install [--path SKILLS_DIR] [--force]
hop skill print

Without --path, Hop installs the same Hop-managed skill files at ~/.agents/skills/hop, ${CODEX_HOME:-~/.codex}/skills/hop, and ~/.claude/skills/hop. With --path, it installs only to SKILLS_DIR/hop.

Git host and collaboration operations

hop host
hop repo create [--host PROVIDER] [--private | --public] [--remote NAME] [--replace-remote] OWNER/NAME
hop issues
hop pulls
hop releases

hop host detects the provider from the push remote. Core Hop commands use Git directly and work without a provider API. Collaboration commands use gh for GitHub, glab for GitLab, and the embedded adapter for Gitea:

clone  whoami  issues  pulls  labels  releases  repos  actions
open   notifications  ssh-keys  api

Examples:

hop issues list
hop pulls create --fill
hop releases view v1.1.4

Unsupported provider capabilities fail clearly without affecting core Hop or Git workflows. The legacy Gitea OAuth/API commands remain available for existing installations.

Exit codes

Exit 20 is a continuation signal for an agent, not a request for the user to manually merge files.