Command and output contracts

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

Scope and coverageCopy Anchor Link

The recursive public inventory has 84 leaves, 284 leaf-owned option occurrences, and 536 effective option occurrences, including three global/built-in flags per leaf. The three additional leaf sections below complete the pinned generated reference within this public 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.

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 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:375 (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:384 (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, setup target results, 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.

V4 owner selection sanitizes a supplied registered name before lookup. V4 has no DNS leaves, authored-native contract, config validate/plan/import/adopt leaves or project task leaves. Do not copy v5 native limits or sensitive env-get error suppression into v4.

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_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}.

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.

---

Source: v4.2.4 · docs/site/reference/command-contracts.md.