Command workflows

The CLI keeps the human workflow small and the automation contract inspectable. Start with a read-only preflight, then run the exact argv you intend to protect.

The command surface

heimdall run [--policy NAME] -- COMMAND [ARGS...]
heimdall agent [--policy NAME]
heimdall config schema|example|validate|explain|show|path
heimdall tls init-ca [--json]
heimdall logs schema|list|path|summary|query|tail|rotate|verify|recover|prune
heimdall init [--dir PATH] [--format toml|yaml|json] [--force]

Inspect without mutation

heimdall agent
heimdall config schema --version v1
heimdall config example --format toml
heimdall config path
heimdall config show
heimdall config validate --json
heimdall config explain --policy default --domain example.com --port 443 --json

heimdall agent is the read-only heimdall.agent/v8 contract. Read execution.backend, owner, privilege setup, and capability evidence before execution.

Evidence stays file-first. Start with heimdall logs summary --run RUN_ID --json for the low-cardinality heimdall.logs.summary/v1 run-health view, then correlate dns.query/dns.answer by data.exchange_id, inspect policy.decision for the matched rule, and use heimdall logs query --run RUN_ID --boundary tls_plaintext.relay --has-blob --jsonl for payloads. Derived http.request/http.response records are bounded HTTP/1 headers whose source_seq values must resolve to explicit plaintext events; common credential headers are masked and bodies stay out of JSONL. Verify referenced SHA-256 blobs with heimdall logs verify. Preview an orphan with heimdall logs recover --run RUN_ID --json; only explicit --apply finalizes the committed prefix as failed and preserves discarded evidence. Retention is also explicit and daemonless: preview and apply logs prune as the invoking user, preserve its JSON deletion evidence, and verify retained runs.

Run through a proxy

heimdall agent
heimdall run -- curl https://example.com
heimdall agent --policy corp
heimdall run --policy corp -- curl https://internal.example.com

The selected policy owns DNS, ordered rules, and final TCP/UDP actions. The wrapped process may re-enter through systemd-run --user --scope; the resolved global config path and exact argv are preserved. No decrypt mode uses a persistent Heimdall daemon.

Relay failures preserve the trust boundary: tls_upstream_certificate_invalid rejects the remote peer, tls_upstream_client_auth_required identifies an upstream mTLS boundary relay mode cannot forward, tls_downstream_certificate_rejected records an explicit client certificate alert, and tls_downstream_closed_without_close_notify remains ambiguous until correlated with child stderr and exit status.

Explain a decision

Preview one TCP or UDP destination without running it:

heimdall config explain \
  --policy default \
  --network udp \
  --domain example.com \
  --port 443 \
  --json

Use --ip instead of --domain for CIDR rules. Omit both to test port-only and final actions. The first matching rule is returned as structured evidence.

Agent contract

Agents should branch on evidence rather than infer support from a language or command name. Inspect:

• execution for foreground ownership and setup privilege drop.
• capabilities.runtime_acceptance for concrete language and protocol paths.
• capabilities.cli_acceptance for command-specific coverage such as Git.
• capabilities.udp before wrapping connectionless or QUIC workloads.
• capabilities.lifecycle for descendants, cleanup, and concurrent isolation.