exocomp docs

Command line interface (CLI)

Global flags, verbs, remote driving, and machine-readable output envelopes.

Reference#reference#cli#commands#flagsDownload Markdown

The exocomp binary functions as both the server daemon (exocompd / exocomp serve) and the primary operator CLI client.

Global flags

These flags apply across all CLI commands:

Flag Env Variable Description
--output <format> EXOCOMP_OUTPUT Output formatting: text (default) or json (also yaml for export)
--remote <target> EXOCOMP_REMOTE Drive a remote daemon over HTTPS / LAN (pinned name or URL)
--token <token> EXOCOMP_TOKEN Bearer token for remote daemon authentication
--idempotency-key <key> EXOCOMP_IDEMPOTENCY_KEY Deduplicate mutating commands to one job
-y, --assume-yes — Answer yes to destructive confirmations (scripts, CI)
--no-input — Refuse confirmations instead of waiting on stdin

(Note: Data directory defaults to $XDG_DATA_HOME/exocomp or /var/lib/exocomp, and can be customized via EXOCOMP_DATA_DIR or --data-dir on lifecycle commands).

Primary verbs

Automation & Execution

  • exocomp playbook run <path>: Run an Ansible playbook against a source.
  • exocomp command run <cmd>: Run an ad-hoc shell command on target nodes.
  • exocomp workspace plan <name>: Generate and seal an OpenTofu execution plan.
  • exocomp workspace apply <name>: Apply an OpenTofu workspace or sealed plan.
  • exocomp provision run <workspace> <playbook>: Execute chained apply → await SSH → onboard → configure workflow.
  • exocomp handoff run <workspace>: Execute the Terraform → Ansible inventory handoff.
  • exocomp jobs list: View active and historic queue jobs.
  • exocomp jobs follow <id>: Stream live events for a running job until terminal.
  • exocomp jobs events <id>: Show a job's append-only event log.
  • exocomp jobs redrive: Idempotently re-run jobs cut off by restart or failure.

State & Secrets

  • exocomp source add/list/sync/rm: Manage registered Git and local sources.
  • exocomp secrets add/list/replace/rm: Manage age secrets envelope entries.
  • exocomp run-secret add/list/rm: Bind sealed secrets to named environment sets for runs.
  • exocomp host onboard/known-hosts: Onboard fleet nodes and inspect trusted host keys.

Checks & Reactive

  • exocomp check add/list/enable/disable/rm: Manage network reachability probe checks.
  • exocomp netgroup add/list/rm: Manage named CIDR network groups.
  • exocomp rule add/list/enable/disable/rm: Manage CEL event-to-job rules.
  • exocomp silence add/list/rm: Temporarily swallow matching reactive events.

Cluster & Maintenance

  • exocomp setup: First-run interactive wizard (identity, recovery kit, backup drill, hand over).
  • exocomp serve: Run the control plane daemon.
  • exocomp doctor: Run environment, permissions, and toolchain checks.
  • exocomp drain: Cordon the daemon and await completion of in-flight work before host reboots.
  • exocomp reload: Reload schedules and push transports from the store without stopping.
  • exocomp restart: Drain in-flight jobs and re-exec the binary in place.
  • exocomp upgrade: Run zero-sudo staged self-upgrade with automated rollback.
  • exocomp backup: Assemble a snapshot and fan it out to configured targets.
  • exocomp restore: Rebuild data directory from a Restic, S3, or Git snapshot.
  • exocomp recovery-kit: Re-render recovery kit structure from stored public data.
  • exocomp kit derive/verify: Derive secrets from the recovery card and verify printed pages.

Machine-readable JSON output

Passing --output json emits a structured RFC 9457-compatible envelope with schema version:

{
  "schema_version": 1,
  "kind": "job",
  "data": {
    "id": "job_01j7abc...",
    "kind": "ansible.playbook",
    "exit_code": 0,
    "duration_ms": 1420
  }
}