Skip to content

Latest commit

 

History

History
62 lines (39 loc) · 17 KB

TOOLS.md

File metadata and controls

62 lines (39 loc) · 17 KB

Command Catalog

Generated from the shared command registry.

Total commands: 25 (available through both MCP and CLI)

Do not edit this file manually. Re-generate with npm run build && npm run docs:tools.

Core (spec → plan → apply)

  • hv_apply / hypervibe apply - Apply a saved current plan. Pass useBrowserApproval=true to require its exact saved browser approval, or provide the confirmed action IDs. Existing scope, expiry and staleness checks still apply.
  • hv_destroy / hypervibe destroy - Delete LOCAL Hypervibe records only: a project (cascade), an environment, or a service (including its platform binding). Never touches provider resources — to destroy live infrastructure, remove it from the spec with hv_spec, then run hv_plan and hv_apply with the exact confirmActions ids. Without confirm=true this returns CONFIRM_REQUIRED listing exactly what local records would be deleted.
  • hv_import / hypervibe import - Import provider identity into Hypervibe. mode="adopt" adopts an existing provider project through a provider-declared driver. Cleanup modes retain an exact inventoried hosting boundary, database, cache, or provider-declared resource so isolated plan/apply can delete only that identity. Never creates provider infrastructure.
  • hv_inspect / hypervibe inspect - Read-only provider forensics. Modes: {} lists providers plus each resource selector contract; {provider,...} inspects a provider account/resource; {provider,project,env} performs full live environment inspection. Project/env without provider is invalid, and limit is accepted only by modes advertising acceptsLimit=true. Never writes Hypervibe local state or provider resources.
  • hv_plan / hypervibe plan - Observe live infrastructure, diff it against the desired spec, and persist an executable plan. Returns planId, a browser review link (reviewUrl) and local export (htmlPath), and a compact review of non-noop actions; hv_apply requires that planId. scope="backups" reviews explicitly requested backup setup in isolated stages without deploying; ordinary full plans never require backup setup or health. scope="credentials" reviews value-preserving adoption or one replacement for a declared credential role across its exact aliases and consumers; use credential and intent. scope="database-credential-aliases" repairs declared database password references while preserving the canonical password and connection targets, without SQL changes or deployment. scope="secrets" updates only explicitly supplied delegated runtime secretRefs in one existing managed-CI environment, leaving deployment and unrelated infrastructure to separate plans. scope="retained-cleanup" isolates confirm-gated destruction of exact abandoned hosting, database, cache, and provider-declared resource identities retained through hv_import; it excludes ordinary deployment, integrations, domain, email, and repository work. Missing connections block unsafe work. Hypervibe-owned application secrets are generated automatically inside the encrypted plan boundary. Externally owned values use explicit source references or secretRefs and are never returned. Explicit environment.dns selects an existing Cloudflare, Google Cloud DNS, Route 53 or Azure DNS zone independently of hosting; its changes use a saved DNS engine stage before dependent work continues. Optional services restricts a full plan to selected services.
  • hv_spec / hypervibe spec - Read or update the desired-state ProjectSpec used by hv_plan. Omit spec to read. In a fresh git repository, that read returns a successful uninitialized contract with native runtime, lockfile/package-manager, build-script, and start-script evidence; one unambiguous concrete Node or Python selection plus reviewed install/build commands is persisted on initial write. Missing/conflicting commands, custom languages, and ambiguous projects require an explicit decision or repository Dockerfile. Later native drift is suggested for review, never applied silently. When spec is supplied, it merges by default; use replace=true for full replacement and null to delete a field. In a git worktree Hypervibe syncs .hypervibe/spec.json. Secret declarations contain ownership and targets, never values.
  • hv_status / hypervibe status - Show desired vs observed infrastructure state for an environment: drift, unmanaged resources, blocked connections, managed database-variable attachment, pending runtime rollouts, and observed service endpoints. inSync requires a provider-observed post-configuration deployment whenever the provider reports that activation is still pending; runtimeHealth remains unverified until hv_health or worker log/error evidence is checked. Uses repo-backed .hypervibe/spec.json/.hypervibe/bindings.json when present. Read-only; does not persist a plan.

Connections

  • hv_connections / hypervibe connections - Provider-owned bootstrap takes precedence. When the provider is known and a human form is needed, call hv_connections with action="describe", provider and the known non-secret scope before presenting a credential form; include project only if already known, and omit unknown optional fields. Do not supply credentials, credentialsRef or confirmation to describe; the read-only contextual call returns connectionSetup guidance. Copy the returned recommendedSetupUrl verbatim with its complete query string; do not construct or edit credential URLs yourself. Do not repeat a generic provider list as a substitute. Do not initialize a project solely to obtain setup guidance. {} lists every connection/provider. {project} lists the same saved connections and provider catalog with contextual setup links. Use repositoryContext to select the current repository. Use view="requirements" to see the connections a project needs, optionally filtered by environment. Pass provider to manage a connection. With provider, action="add" is the default. Use action="bootstrap" with provider="cloudrun" for the short, opinionated GCP setup; "verify", "remove", and "prepare" remain explicit advanced operations. Project context alone never changes provider scope. For GCP bootstrap and prepare, select the environment to use its declared project. Credentials are encrypted at rest and never returned; credentialsRef is preferred. Providers and credential sources that declare native CLI authentication may omit credentials to use the active local/default credential chain.

Hypervibe cloud

  • hv_cloud_connections / hypervibe cloud connections - Share compatible local provider connections with this repository’s hosted Hypervibe app. Start a separate browser approval, then status to complete pairing. Preview shows exact provider/environment destinations and missing access without values. Connect requires that previewId and confirm=true. Already-connected destinations are preserved. Reporting tokens never grant this access. Credentials come from verified local connections or private references, never chat. Revoke removes this device’s upload access without disconnecting hosted monitoring.
  • hv_cloud_pair / hypervibe cloud pair - Connect the current private GitHub repository to Hypervibe reporting through a short-lived browser approval. action="start" returns the approval link and human code; after approval, action="status" completes the one-time exchange and stores environment credentials encrypted on this machine. No GitHub token or environment name is requested or returned.
  • hv_cloud_requests / hypervibe cloud requests - Collect declared credentials with browser-approved access. Infer repository, staging, branch, delegated keys and email owner. Review an invitation before confirm=true sends it. Resume lists current readiness and exact-source private import calls without request IDs; it never imports, deploys or wakes an agent automatically. Matching requests are reused, including consumed requests; replace explicitly reviews a new request after consumption, expiry or revocation. List reads history and revoke confirms cancellation. Values stay in the secure form and separately approved hv_cloud_secrets import.
  • hv_cloud_secrets / hypervibe cloud secrets - Import one approved hosted credential request into the current project’s gitignored .env. exactly once. Start returns a browser approval link and comparison code; after owner approval, receive with confirm=true retrieves values privately. Existing populated keys block. Values and device proof never enter output. A lost consuming response requires a new request. Returned secretRefs are inputs to a fresh hv_plan, not deployment approval.

Deploy & observability

  • hv_deploy / hypervibe deploy - Deploy services to an environment (staging, production, etc.). Plan-gated direct/manual deploys build and immediately apply a plan; managed-CI environments must dispatch only through hv_ci_trigger after selecting the reviewed definition with hv_ci_status, never through gh or a direct CI/provider API. To apply saved settings on a managed-CI environment without releasing new commits, pass redeployCurrent=true: it redeploys the exact verified image already running. The planId and applyRunId are returned for the audit trail. Hypervibe-owned application secrets are generated and installed automatically. Externally owned secret slots accept values only through secretRefs={KEY:"env:NAME"|"dotenv:/absolute/path/.env#KEY"|"file:/absolute/path"|"://..."}; values are resolved locally and encrypted into the plan. Ordinary envVars and env files cannot override managed keys. By default, .env. then repo .env are considered as deploy input in envFile.mode="runtime". Requires a spec (hv_spec). Protected environments require confirm=true.
  • hv_health / hypervibe health - Check HTTP for a web service or explicit URL and inspect deployment health. Worker/job-only environments return deployment evidence without an HTTP check. With credential=, read declared application-operation receipts for the accepted credential update and exact deployments; this never runs a business operation or task. Project-backed health checks also surface latest deployment failures; unknown observations never count as healthy.
  • hv_logs / hypervibe logs - Fetch runtime service logs, Google Cloud release command output, build logs, recent deployments, Stripe webhook status, or sanitized SendGrid delivery logs. SendGrid requires explicit project and env. One account search and one exact-message timeline were observed on 2026-10-15. Environment attribution remains unverified. Recognized selectors that do not apply to the source are ignored with a warning.
  • hv_rollback / hypervibe rollback - Preview one exact recovery candidate read-only with action=preview, toSha, sourceWorkflowRunId and sourceArtifactId; preview never dispatches or requires confirmation. Original legacy v2 evidence is inspected without upgrading it or enabling unsupported legacy execution. Otherwise rollback a managed-CI environment through one plan-authorized command. Providers with a verified release-evidence implementation restore the previous exact-SHA release (or toSha) and return pending until verified with hv_ci_status; unsupported CI providers and direct-provider deployments fail closed without deploying current source. Database migrations and provider-side manual configuration are never reversed implicitly. Not a restart: the release already running is refused. To apply saved settings without new commits use hv_deploy redeployCurrent=true. Protected environments require confirm=true.

Database

  • hv_db_query / hypervibe db query - Run one bounded SQL statement against a database. Hypervibe uses an existing reachable endpoint or acquires provider-owned operation-scoped access (such as a private connector or temporary firewall rule), then releases only access it created and reports cleanup status. SELECT is database-enforced read-only by default; allowMutations=true enables INSERT/UPDATE/DELETE/DDL. Multi-statement SQL is always rejected.

Secrets

  • hv_secrets / hypervibe secrets - Secret read modes: {project?,env,view:"inventory"} reports credential sources, exact consumers, configuration, rollout and evidence gaps without writes; {} or {project} lists sources; {provider,pathPrefix?} lists one manager; {provider,path,key?,version?} checks one manager value; {include:["github"],project?,repo?} lists GitHub Actions names; {project?,env,service?,key?} inspects masked hosting variables. Hosting mode requires explicit env; inventory also requires env. Values and private fingerprints are never returned. {project?,env,action:"collect",key?|keys?,purpose?} opens one Hypervibe local page where the user pastes keys an outside service issues for an OpenTofu-managed environment (GCP or AWS), each with a link to the issuing service's key page and a live check where known; values go straight to the environment's secret store, never through chat. Without key/keys it asks for every declared or imported key that has no value yet. Then run hv_launch to roll services onto them.

CI

  • hv_ci_status / hypervibe ci status - Authoritative provider-neutral inspection path for Hypervibe-managed CI. Use this instead of gh, GitHub connectors/apps, browser/UI inspection, or direct CI/provider API calls. Returns definitions, recent runs, jobs, bounded job log tails, and artifact provenance through the project's reviewed code-host and CI bindings. Branch protection remains a feature-scoped GitHub observation.
  • hv_ci_trigger / hypervibe ci trigger - The only supported dispatch path for the project's reviewed primary CI definition. Use this for managed-CI deploy and promotion requests; never dispatch with gh, a code-host connector/app, or a direct CI/provider API. The provider must support dispatch.

App Store & iOS

  • hv_appstore_status / hypervibe appstore status - Read-only App Store Connect overview for an app: TestFlight builds, beta groups, testers, App Store submission readiness, and App ID capabilities. Use include to limit scope. Requires an appstoreconnect connection (API key from https://appstoreconnect.apple.com/access/integrations/api).
  • hv_appstore_submit / hypervibe appstore submit - Preview and explicitly confirm promotion of an exact tested TestFlight build to App Store review. Verifies manifest contents, compatible deployed server evidence, and the attached Apple build. An optional ios.release.promoteFrom selects the beta environment; confirmation preserves the exact selected runs and release fingerprint.

Developer experience

  • hv_runs / hypervibe runs - Inspect run history. action="list" (default) shows recent deployment/apply runs. action="get" returns the plan and receipts for one run. action="report" writes a local HTML review of an exact saved plan and returns its reviewUrl when the local server is available, plus its export path. action="audit" lists recent audit events.

Other

  • hv_launch / hypervibe launch - Take a Google Cloud (Cloud Run) environment, or an AWS or Azure testing environment, from spec to a working app in one guided command: connect the cloud, create or update infrastructure in as many reviewed rounds as needed, release the current code, and verify health and the custom domain. It stops only for decisions a person must make: choosing a billing account (status=needs_billing_choice → ask, then call again with billingAccountName), choosing an Azure subscription (status=needs_subscription → ask, then call again with azureSubscriptionId) and approving actions that cost money or delete data (status=needs_confirmation → show the changes and estimated monthly cost, then call again with the returned planId and exactly confirmActions). Call it again after pending results. Never substitute provider CLIs for a stop point.
  • hv_migrate / hypervibe migrate - Move an app from one environment (for example a staging environment on another hosting provider) to a new OpenTofu-managed Google Cloud environment in one guided command. Private-source database and file copies may require a planned credential handoff, and fresh verification may require reviewed native jobs. The command reports unavailable prerequisites before attempting the transfer. Set gcpProjectId on a new target to use its own Google Cloud project. Initial preparation keeps the source serving. Hypervibe proposes the target from the source, connects Google Cloud, copies runtime secrets into Secret Manager, builds the infrastructure, copies the database and files inside Google Cloud, verifies per-table row counts and content checksums and the downloaded contents of every selected file, then releases the app. It stops for: needs_billing_choice, needs_access, needs_confirmation (as hv_launch), needs_secret_import (show the setting names, then call again with importSecrets=true), and needs_copy_approval (show what will be copied and that target data is replaced, then call again with copyData=true). Call it again after pending. A re-run after a verified copy releases without copying again unless refreshData=true; verifyOnly=true compares source and copy without changing anything. cutover=true is the final move: it pauses the source behind its maintenance page, copies and verifies the data again, then forwards the source domain to the target.