CLI reference — macfor docs

Top-level usage

macfor [global flags] <command> [command flags]

Commands:
  list         List available plugins and categories
  collect      Collect artifacts into an evidence container
  manifest     Inspect or validate plugin manifests
  help         Show contextual help

Global flags:
  --log-level   trace|debug|info|warn|error   (default: info)
  --json-logs   Emit zerolog JSON to stderr
  --version     Print version and exit

list

List the plugins compiled into the binary.

macfor list plugins
macfor list plugins --json
macfor list plugins --category browser
macfor list plugins --category communication --json

The --json form is stable; safe to feed into a downstream tool that needs to know which collectors are available before invoking collect.

collect

The primary command. Resolves sources, runs plugins, and writes the evidence container.

macfor collect \
  --output ./evidence.zip          # Required. Path to evidence container.
  [--plugin <id>]                  # Repeatable. Collect only the listed plugins.
  [--category <name>]              # Repeatable. Collect every plugin in the category.
  [--source live|image:<path>]     # Default: live system.
  [--user <name>]                  # Repeatable. Limit per-user artifacts to these users.
  [--include-optional]             # Include artifacts marked optional in the manifest.
  [--dry-run]                      # Resolve paths and report; do not write the container.
  [--continue-on-error]            # Default true. Use --no-continue to abort on first error.

Common invocations

# Triage: only browsers + shell, current user
macfor collect \
  --plugin shell.history \
  --category browser \
  --output ./triage.zip

# Full sweep, multi-user (requires root + Full Disk Access)
sudo macfor collect --output ./full.zip

# Disk-image collection
macfor collect \
  --source image:/Volumes/Evidence \
  --output ./evidence-image.zip

Exit codes

0 — success, container written and verified.
1 — collection ran with one or more plugin errors. Container is still written; check the per-plugin logs inside.
2 — usage error (bad flags, no plugins matched).
3 — fatal I/O error before the container could be sealed.

manifest

Operate directly on plugin artifacts.yaml manifests — useful for plugin authors and for writing custom triage scripts.

# Validate one or more manifests
macfor manifest validate plugins/*/artifacts.yaml

# Print the resolved on-disk paths a plugin would read
macfor manifest paths --plugin browser.safari

# Artifact location catalog: every artifact, its version-aware locations,
# and how it is parsed (declarative / native / planned), per OS and app version
macfor manifest matrix --plugin browser.safari
macfor manifest matrix --markdown
macfor manifest matrix --json

# Emit Markdown documentation derived from every loaded manifest
macfor manifest docs > artifacts.md

manifest pack

Out-of-band manifest packs are signed, versioned bundles of artifact manifests that can be distributed and validated independently of the binary. A pack is a directory containing the manifest YAMLs, a pack.yaml (version plus a SHA-256 per manifest), and a detached pack.sig. Packs carry declarative configuration only — they can never reference native parser code — and the embedded plugin manifest remains the source of truth for collection.

# Show a pack's version, digest, and per-plugin content hashes
macfor manifest pack info ./pack-dir

# Sign a pack (writes pack.sig) with an ed25519 private key
macfor manifest pack sign ./pack-dir --key key.hex

# Verify a pack's signature and constraints against a trusted public key
macfor manifest pack verify ./pack-dir --pubkey pub.hex

Logging

macfor uses zerolog. Default output is human-friendly on a TTY; flip --json-logs for machine ingestion. Per-plugin logs are also archived inside the evidence container under logs/<plugin_id>/collection.log.