Command and output contracts

This field inventory was audited against the 5.0.0-next.5 source and has not been requalified against later prereleases. The generated command reference and the pinned runtime guides take precedence where they differ.

Pinned source: 28de2f8902d3776c3da9326e7ae6c6aa6e7f69bc. This supplements the generated command reference. Command registration and document shape do not establish backend admission.

Scope and coverageCopy Anchor Link

The pinned source inventory has 92 leaves, 335 leaf-owned option occurrences, and 611 effective option occurrences. The recommended v5 publication selection retains 84 leaves, 288 own option occurrences and 540 effective occurrences (three global/built-in flags per leaf). Eight retiring agent-setup leaves and init's optional handoff flag are intentionally excluded; they remain available in the released source. The six additional leaf sections below complete the pinned generated reference within the retained command scope. No declared effective flags or short aliases are missing from matching sections; generic value placeholders explain initial spelling-only differences. Counts are occurrences, not unique names. Parent namespaces are not leaves.

Retired gateway/node/remote/dispatch, hosted account/team/Tickets, internal helpers, extension dispatch and fun commands are excluded. SSH remote access is excluded. Retained fields within local commands do not establish support for retired backends.

The retired agent instruction-management commands (hack setup sync, standalone hack setup exports and hack agent prime) are omitted; in v5 they refuse with a retirement notice. See Agent integrations.

Global flags and parsingCopy Anchor Link

Every leaf accepts --no-interactive, --help, -h, and --version, -v. The first also has HACK_NO_INTERACTIVE=1; it applies documented defaults or refuses required interaction. Help/version return early with status 0. These are the only inherited flags: parent options are not inherited. Omitted booleans parse false; omitted strings/numbers parse undefined. Handler/config fallbacks are separate. A nonboolean OptionSpec defaultValue supplies a value when the flag is present without its value; it is not an unconditional omitted-flag default.

Additional command detailsCopy Anchor Link

hack global dns previewCopy Anchor Link

Preview a scoped native custom-domain DNS claim or the hack.local relay repair without changing the host.

Arguments: none.

Source: src/commands/global.ts:232 (globalDnsPreviewSpec). No command alias is declared.

hack global dns activateCopy Anchor Link

Activate only the selected native custom-domain DNS suffix.

Arguments: none.

Source: src/commands/global.ts:252 (globalDnsActivateSpec). No command alias is declared.

hack global dns deactivateCopy Anchor Link

Remove an owned native custom-domain DNS suffix, or undo the hack.local relay repair.

Arguments: none.

Source: src/commands/global.ts:270 (globalDnsDeactivateSpec). No command alias is declared.

hack project owner showCopy Anchor Link

Show the local ownership metadata for the current project.

Arguments: none.

Source: src/commands/project-admin.ts:16 (ownerShowSpec). No command alias is declared.

hack env backend statusCopy Anchor Link

Show configured env/secret backend strategy.

Arguments: none.

Source: src/commands/env.ts:428 (backendStatusSpec). No command alias is declared.

hack env backend use <backend>Copy Anchor Link

Select env/secret backend strategy.

Arguments: backend — required.

Source: src/commands/env.ts:437 (backendUseSpec). No command alias is declared.

Complete public leaf and flag inventoryCopy Anchor Link

“Present” means a matching usage section; flags were compared separately. It does not prove every handler default is described. All rows also accept the three global/built-in flags above. Arguments are exact spec names.

Declared defaults and option semanticsCopy Anchor Link

This table preserves declarations/descriptions that state defaults. Other handler/backend defaults are not implied by absence here.

Ownership inspectionCopy Anchor Link

project owner show searches from cwd or --path, or selects a registered --project; do not combine path/project. Missing project and config parse failures refuse. JSON success is a bare object and exits 0:

Defaults are local/user/null/local. These are retained local metadata, not hosted team/broker support. No owner mutation leaf exists here.

Env backend strategyCopy Anchor Link

Status reads effective settings for cwd's project when found, global settings otherwise. It takes no project/path/env selectors. Use writes global settings and rereads global settings. It does not migrate YAML project-key values or establish cloud-provider qualification.

Backend is required: exactly keychain, encrypted_file or cloud. Provider accepts exactly aws|gcp|azure|vault and is required for cloud even if a provider was previously configured. Invalid nonempty backend/provider is a usage error. Inputs are trimmed; empty optional paths/project/prefix are omitted. Store/key paths apply only to encrypted_file; cloud project/prefix apply only with cloud/provider. Omitted settings are retained. Provision-key defaults false and applies only to encrypted_file.

Fresh schema defaults: keychain, allow_env_auth_refs true, store_plaintext_in_backend false; file path ~/.hack/secrets.enc.json, key path ~/.hack/secrets-file.key; cloud prefix hack, provider/project unspecified. These are config defaults, not flag defaults reapplied on every use. The key environment variable name is HACK_SECRETS_FILE_KEY. Providers describe retained compatibility strategies, not qualified cloud onboarding.

Both JSON successes are bare objects and return 0:

Status has string storage_mode/trust_model/portability/plaintext_compatibility and classification. Classification has string trust_model/custody/portability and shared_state (local_only/plaintext_compatible/portable_bundle/broker_managed). These descriptive names do not grant remote/team features.

JSON results and exitsCopy Anchor Link

The generated page's universal envelope claim is too broad. Decode by command and backend. The shared helper emits {ok:true,data:T} or {ok:false,error:{code,message,detail?}}; detail is unknown. Its mapper returns 0/1. Handlers can instead return child exit codes, bare objects, reports or JSON-lines.

Thrown usage errors with an explicit --json token become E_USAGE; other thrown errors preserve HackCliError codes or become E_UNEXPECTED, with exit 1. Returning 1 directly does not automatically create an error envelope. Unknown command or namespace paths may print help and exit 1. Help/version return early with status 0, including when JSON was requested. Valid JSON alone proves neither success nor readiness.

Config get has no JSON flag: non-string values serialize as JSON, strings print plainly. Daemon metrics prints retained metrics JSON without a JSON flag; nested internal transport data is not a supported general API. MCP serve speaks MCP; log-pipe formats a stream. Other leaves without JSON do not inherit it.

Report detailsCopy Anchor Link

Direct projects/status fields: generated_at, filter, include_global, include_unregistered, include_meta, runtime_ok, runtime_error, runtime_checked_at, runtime_last_ok_at, runtime_reset_at, runtime_reset_count, runtime_reset_summary, runtime_reset_changes, runtime_last_repair_at, runtime_repair_action, runtime_repair_outcome, runtime_next_step, projects[]. Optional detail_level:summary selects summary projection. Project records use summary/full projections with optional meta. Nullable recovery metadata is not liveness proof; nested engine/meta variants remain open.

Prune preview and apply are separate shapes. Apply includes runtimeOk/runtimeError, removedRegistryEntries[] (id/name/repoRoot/projectDir/reason), removedOrphanedProjects[] (project/workingDir/reason/containerCount), removedContainerCount. Preview includes dryRun:true, runtimeOk, registryCandidates[] (name/projectDir/reason), orphanedProjects[] and candidateContainerCount. It does not add runtimeError merely because apply has it. Orphan records are typed in the table below.

Doctor checks contain id/status/detail/durationMs; status is ok/warn/error. summary is string[]; counts are numbers. Additional diagnostics depend on version/check and remain specialized shapes.

Daemon status fields: status, running, api_ok, api_reachable, api_compatible, process_running, stale, stale_reason, issue, next_step, pid, socket_path, socket_exists, log_path, log_exists, launchd. Launchd is null or {installed,loaded,running,pid,exit_status,plist_path}. Unavailable/nullable observations must not be treated as proof of process absence or authority to signal a PID.

Env explain: key:string, available/secret:boolean, format:project_env_config_v1/legacy_env_contract; environment/effective_scope/source:string|null; requested_scope:string, target:host/compose, delivered_to/precedence:string[]. It emits no value.

Env list: project and env_selection (requested/default/effective selections, overlay_path, overlay_exists). Modern YAML adds format:project_env_config_v1, selected_scope, scopes, files, unknown_scopes, status/storage descriptions, vars[], missing_required. Legacy reports have storage/status, materialization and key projections. Rows in vars[] contain key/required/source/services/resolved_from/storage/value. Secret values are masked unless show-secrets is explicitly selected; ordinary plaintext is not thereby hidden. Modern reports include materialized when show-secrets is selected, otherwise materialized_keys. Legacy reports additionally contain warnings[] (kind/key/overlay_path/services/message). CLI reports differ from MCP's narrower value-free keys projection. Nested modern/legacy variants remain versioned report shapes; application values are not new stable reference keys.

Compose/Loki log recordsCopy Anchor Link

Logs JSON is newline-delimited events, not an array or envelope. Finite snapshots and follow share vocabulary. Follow is default; no-follow requests finite output. Omitted tail falls back to 200. JSON conflicts with pretty; compose conflicts with explicit Loki selection (loki/services/query/since/until); follow with until refuses.

Compose ends with eof or exit:. Loki finite snapshots can end without reason; handled query failure emits error/end(error), follow ends closed/error. Error can precede start. Heartbeat has a builder, but these emitters do not establish periodic delivery. End settles a stream, not a workload.

Optional fields are omitted, not declared nullable. Map keys are open application data. The TypeScript declaration is not a runtime-validated closed JSON schema. Global logs has no JSON option.

Session JSON-linesCopy Anchor Link

Panes/capture/tail are tmux inspection surfaces and default to JSON unless pretty is selected. Capture/tail default to active target and 200 lines. Tail defaults interval-ms to 500 and max-ms to 5000. JSON and pretty together refuse. Panes snapshots emit start, log per pane, end(snapshot); capture emits log per captured line and end(snapshot). Tail emits changes and a finite budget ends with timeout. Refusals can precede event creation.

All events have type start/log/error/end, ts:string (ISO), session:string. Pane logs add pane:{target:string,active:boolean,windowIndex:number,windowName:string,paneIndex:number,command:string,path:string|null}. Capture/tail events also have target:string, lines:number, follow:boolean, optional intervalMs/maxMs:number. Log adds line:string; error adds message:string; end may add reason:string. These are separate from project log entry/backend events.

Remaining limitsCopy Anchor Link

Leaf/flag presence is reconciled. Handler defaults outside the reviewed tables are not an exhaustive semantic audit. Engine rows, optional diagnostic subtypes, listing metadata, update success variants, nested env variants and candidate reports remain bounded open/specialized shapes. No closed schema, backend parity, client-loading proof or installed runtime acceptance is claimed. Config-file/MCP field work remains in the separate audit. Private compiler/daemon/guest/provider protocols and retired APIs are excluded.

v5 native support limitsCopy Anchor Link

The inventory preserves retained Compose contracts. A listed flag is not proof of native admission. next.5 has no project task leaves; no newer task/target contract is backported.

Authored native projects require explicit native backend selection on macOS, separately prepared matching provider/runtime, absolute native binary and private native home. The pinned TypeScript authored frontend admits whole-project foreground up/restart, owner-mediated down and explicit bounded recovery, saved-run ps, finite service logs with no-follow, noninteractive service exec and one-off run at source level. Up/restart refuse detach/JSON and service subsets. Source/storage/routing/network/lifecycle admission remains bounded by the pinned authored-command guide. This is experimental support, not Compose parity.

Authored native ps JSON uses the shared envelope: data.backend:native, status:not_started/pending/runtime_not_running/observed, run/phase:string|null, items[]. Authored items have service/container/state:string, health:string|null, exitCode:number|null. The separate legacy native projection has statuses not_started/runtime_not_running/observed/owner_unconfirmed/runtime_degraded and item fields service:string, container:string|null, phase/state:string, health:string|null, exitCode:number|null. Fresh observations supply health/state; saved readiness/phase is historical. Ownership uncertainty can refuse.

The legacy native graph logs path returns bare {backend:native,run,service,container,stdout,stderr,truncated}; strings except truncated:boolean (container reflects selected owned row). Authored finite logs uses the same top-level names with container:string; neither should be parsed as Compose/Loki events. Authored service grammar is [A-Za-z0-9_.-]{1,128}, and tail is an integer 1–1000, default 200. Only bounded service/no-follow/tail/JSON selection is admitted; profiles, explicit backend overrides, service lists, query/time filters and pretty refuse. The retained legacy native Compose frontend has narrower admissions than authored native: do not borrow authored run/restart support.

Candidate-only DNSCopy Anchor Link

The source hint v5.hack.gy is an example suffix, not a fixed literal. Omission uses configured custom global default_domain; an unset/built-in default does not silently claim hack.local/hack/hack.gy.

All three leaves require explicit macOS native candidate selection. Preview performs inspection, not host writes. Custom preview JSON: {ok:true,data:{domain,status,dnsmasqPath,resolverPath,receiptPath,address,activation}}. Fields are strings except activation:string[]; status available/active describes disk/receipt state, not live DNS proof.

Explicit hack.local preview returns a route report with dnsmasqPath/resolverPath/receiptPath:string, receiptState nullable, status current/repairable/refused. Current adds relayPort and optional command; repairable adds oldLine/newLine/resolverAction/relayPort/command; refused adds reason/detail and optional command. Preview can exit 0 with refused data.status.

Activate has no JSON and refuses hack.local, which uses doctor repair. Making a new custom claim requires interactive confirmation/admin authorization and unchanged inspected inputs; an already active claim is verified. Deactivate has no JSON: it removes only an owned custom claim and verifies fallback resolution, or explicitly rolls back hack.local repair. Changed/unproven inputs refuse. There is no yes/force bypass flag.

Other v5 report differencesCopy Anchor Link

Config validate/plan print candidate reports directly, with transport_version/ok and diagnostics or success projections. Transport failure is {transport_version:1,ok:false,error:{code,message}}. Import dry-run and adopt preview print complete/fields reports; completed adoption has its own operation report. These evolving CLI projections do not publish internal compiler transport, plan, journal or guest DTOs.

Listing can add filter_redacted:true; v4 lacks this. Doctor adds check-dependent supersededRoots/hackLocalRoute/envKey diagnostics; nested variants remain specialized.

Sensitive env-get failures use fixed stderr-only text and status 1, even if unsupported JSON was supplied. This does not add a JSON option.

Parent command sectionsCopy Anchor Link

These sections are also present in the pinned reference. Some parents handle direct invocation (for example projects/session); namespace options do not pass to children. Counts above count terminal leaves only.

Stable shared error codesCopy Anchor Link

E_DOCKER_UNAVAILABLE, E_GLOBAL_INFRA_DOWN, E_CONFIG_PARSE, E_CONFIG_INVALID, E_PROJECT_NOT_FOUND, E_NATIVE_PROJECT_CONFLICT, E_NATIVE_PROJECT_UNSUPPORTED, E_NATIVE_COMPOSE_PROXY_ACCESS, E_SERVICE_NOT_FOUND, E_COMPOSE_FAILED, E_STARTUP_INCOMPLETE, E_DEPENDENCY_BOOTSTRAP_FAILED, E_STARTUP_TIMEOUT, E_LIFECYCLE_FAILED, E_ENV_KEY_MISSING, E_PERMISSION, E_INTERACTIVE_REQUIRED, E_USAGE, E_UNEXPECTED. Optional error.detail is unknown; direct-return failures need not use this envelope.

Update success fields: ok:true, current/latest:string, updateAvailable/installed:boolean, target:{platform:string,arch:string}, binaryPath/assetsDir:string, optional mutagen provisioning report. Handled failure is {ok:false,error:string}.

DNS relay-report fields: relayPort:number; oldLine/newLine/command/detail:string; resolverAction:keep/create; receiptState is null or the retained repair receipt state. Custom address is a string. Report paths/lines are descriptive and do not grant ownership or repair authority.

Typed corrections for generated value placeholdersCopy Anchor Link

These were display-only mismatches, not missing flags. The generated <value> placeholder means a value is required when the flag is used; none of these options has a short alias or an OptionSpec defaultValue.

Prune preview field typesCopy Anchor Link

The preview uses the shared success envelope. Its data object is:

Preview omits runtimeError. A successful envelope describes a completed preview, not a guarantee that the runtime is healthy. Apply has the distinct removal fields already listed above. Neither form is permission to delete resources.

Exact native admission and launcher boundaryCopy Anchor Link

All claims here are source admission, not runtime-verified or installed-release support.

The pinned comparison table and authored dispatch describe different admission boundaries. Use the source-specific distinctions above; source admission does not qualify a provider or application. Installed matching-bundle acceptance and live provider behavior remain unverified. Task leaves absent at next.5 remain excluded.

---

Source: next.5 field audit · docs/reference/cli.md.