CLI Reference

mallcop init

Discover environment, write config, estimate costs.

mallcop init [--pro]

Scans for available connectors (Azure, AWS, GitHub, M365, Vercel, container-logs, Supabase, OpenClaw), authenticates each, pulls a sample of events, writes mallcop.yaml with discovered connectors and budget defaults, and outputs a cost estimate with required secrets.

With --pro, creates a Pro account using the email from git config user.email, gets a plan recommendation based on discovered connectors, and adds the pro section to config with managed inference credentials.

mallcop scan

Poll all connectors, store events.

mallcop scan

Authenticates each connector configured in mallcop.yaml, polls from the last checkpoint, applies parser transforms for container-logs apps with parser.yaml, and appends new events to the JSONL store. Outputs per-connector event counts and checkpoint values.

mallcop detect

Run detectors against new events.

mallcop detect

Loads all events and the baseline, determines which connectors are still in learning mode (14-day window), runs all built-in and custom detectors, persists findings, then updates the baseline with new events. Learning-mode findings are informational only.

mallcop escalate

Invoke actor chain on open findings.

mallcop escalate [--human] [--no-actors] [--backend anthropic|claude-code]

Runs the configured actor chain (triage, investigate, notify) on all open findings. Validates escalation paths before running — if notification channels are broken, the command fails immediately rather than silently dropping alerts.

mallcop watch

Scan + detect + escalate in one command. Designed for cron.

mallcop watch [--dry-run] [--human] [--backend anthropic|claude-code]

Runs the full pipeline: scan, detect, escalate. Validates escalation paths before starting. Skips escalation during learning mode or with --dry-run. This is the command you schedule every 6 hours via cron.

mallcop review

Orient: load the POST.md playbook and all open findings.

mallcop review [--human]

Displays the current investigation playbook (POST.md) and all open findings grouped by severity, with annotations from previous actor runs. Suggests commands for the next investigation step. Use this as the starting point for interactive investigation.

mallcop investigate

Drill down: POST.md + deep context for one finding.

mallcop investigate FINDING_ID [--human]

Loads a single finding with full context: triggering events, actor history, baseline profile for involved actors, and all annotations. Includes the investigation playbook (POST.md) for reference. Use after mallcop review to deep-dive into a specific finding.

mallcop finding

Full finding detail + annotation trail.

mallcop finding FINDING_ID [--human]

Shows the complete state of a single finding: title, severity, status, detector, timestamp, event IDs, metadata, and the full annotation trail with timestamps and actor names.

mallcop events

Query events from the store.

mallcop events [--finding ID] [--actor NAME] [--source NAME] [--hours N] [--type TYPE] [--human]

Queries the event store with optional filters. Defaults to the last 24 hours. When filtering by finding, the time window is ignored and only the finding's triggering events are returned. Results are sorted newest first.

mallcop baseline

Query baseline data.

mallcop baseline [--actor NAME] [--entity NAME]

Without flags, shows general baseline stats: event count, known actor count, frequency table entries, and known sources. With --actor, shows the full baseline profile for that actor including frequency entries and relationship data. With --entity, checks whether a specific entity is known in the baseline.

mallcop report

Show findings report with optional filters.

mallcop report [--status STATUS] [--severity LEVELS] [--since WINDOW] [--human]

Queries findings with optional status, severity, and time filters. Severity accepts comma-separated values (e.g. critical,warn). Time window uses the format 24h, 7d, or 30m.

mallcop annotate

Add an investigation note to a finding.

mallcop annotate FINDING_ID TEXT [--author NAME] [--human]

Appends a timestamped annotation to a finding's trail. Use this to document investigation reasoning before resolving. Annotations are visible in mallcop finding and mallcop review output.

mallcop ack

Resolve a finding and update the baseline.

mallcop ack FINDING_ID [--author NAME] [--reason TEXT] [--human]

Marks a finding as acknowledged, adds an annotation to the trail, and updates the baseline with the finding's triggering events so the same pattern is recognized as known in future scans. Boundary-violation findings cannot be acked — the underlying violation must be fixed. Double-acking is rejected.

mallcop feedback

Record human feedback on an agent finding.

mallcop feedback FINDING_ID agree|override [--reason TEXT]

Records whether the agent's decision was correct (agree) or wrong (override). Captures a snapshot of the finding's events, baseline state, and annotations at the time of feedback. This data feeds the self-improvement loop. Includes a cadence check that warns if feedback is being rubber-stamped too quickly.

mallcop status

Event/finding counts and operational status.

mallcop status [--costs] [--human]

Shows total events, total findings, events by source, findings by status, and escalation health. With --costs, adds cost trends: average donuts per run, total donuts, estimated USD, and circuit breaker trigger count. Always checks whether escalation paths are working.

mallcop upgrade

Switch tiers or add managed inference.

mallcop upgrade

Handles plan tier changes: upgrade from free to Pro, switch between Pro tiers (Starter, Growth, Scale), or add managed inference to an existing BYOK setup. Prorated billing for mid-cycle upgrades.

mallcop heal

Review and apply parser patches proposed by the heal actor.

mallcop heal [--auto] [--dry-run] [--human]

Scans for log-format-drift findings with heal actor annotations containing parser patch proposals. If no heal annotation exists, runs inline drift analysis to generate proposals. Patches update parser.yaml templates to match new log formats.

mallcop patrol

Manage scheduled patrols (cron-based watch/research runs).

mallcop patrol create NAME --every PERIOD [--budget N] [--chain ACTORS] [--notify CHANNELS] [--research] [--no-git]
mallcop patrol list
mallcop patrol update NAME --every PERIOD
mallcop patrol disable NAME
mallcop patrol enable NAME
mallcop patrol remove NAME
mallcop patrol run NAME

Patrols are named scheduled runs managed via crontab. Each patrol has a period (15m, 1h, 6h, 1d, 1w, 1mo), an optional donut budget, actor chain override, and notification channel list. Patrol config is stored in mallcop.yaml and crontab entries are managed automatically.

mallcop research

Research OSINT advisories and generate detector rules (Pro only).

mallcop research [--human]

Queries OSINT advisory sources, checks each against the intel manifest to skip duplicates, and uses the LLM to generate declarative detector rules for relevant advisories matching your configured connectors. Requires a Pro subscription with pro.service_token in mallcop.yaml.

mallcop discover-app

Sample container logs for an app, output structured context.

mallcop discover-app APP_NAME [--lines N] [--refresh]

Samples recent log lines from a container app via Log Analytics, analyzes log format patterns, and outputs structured context for building parser.yaml templates. Use when onboarding a new container app or after a log format change.

mallcop exam run

Run Academy Exam scenarios and output grades.

mallcop exam run [--tag TAG] [--scenario ID] [--model MODEL] [--human] [--backend BACKEND]

Loads adversarial scenarios from the shakedown suite and runs them through the actor chain. Each scenario tests whether the AI correctly resolves or escalates a finding. Filter by failure mode tag (KA, AE, CS) or run a single scenario by ID. Requires LLM credentials or --backend claude-code.

mallcop exam bakeoff

Benchmark models for pricing and performance.

mallcop exam bakeoff --pricing PRICING_PATH [--models ALIASES] [--profile AWS_PROFILE] [--region REGION] [--judge-backend BACKEND] [--output PATH] [--human]

Runs all Academy Exam scenarios against multiple Bedrock commodity models, grades each with an LLM-as-judge, and produces a diffable summary JSON with routing recommendations per sovereignty tier. Requires AWS SSO credentials and boto3.

mallcop improve

Analyze exam results and propose detector/prompt improvements.

mallcop improve [--from-exam RESULTS_FILE] [--human]

Loads graded exam results and identifies failure patterns. Groups scenarios by failure mode, suggests fix targets (actor chain, detector rules, playbook prompts), and provides improvement directions. Run mallcop exam run first to generate the input file.

mallcop scaffold

Generate a plugin directory with manifest and stubs.

mallcop scaffold connector|detector|actor|tool NAME

Creates a plugin directory under plugins/ with a manifest.yaml and stub Python files matching the plugin contract. Four plugin types are supported: connector (polls APIs), detector (flags anomalies), actor (investigates findings), and tool (gives actors capabilities).

# Examples
mallcop scaffold connector cloudflare
mallcop scaffold detector unusual-geo
mallcop scaffold actor deep-investigate
mallcop scaffold tool query-dns

mallcop verify

Validate a plugin against its contract.

mallcop verify PLUGIN_PATH
mallcop verify --all

Checks that a plugin directory has a valid manifest.yaml, implements the required interface methods, and passes contract tests. Supports connectors, detectors, actors, tool files (.py), and app artifact directories (containing parser.yaml or detectors.yaml). With --all, discovers and verifies all plugins in the current directory.

mallcop skill list

List all installed skills with their metadata.

mallcop skill list

Shows all skills available in the skills directory: name, description, version, author, parent, and signature status. Includes both built-in skills (signed with the mallcop root key) and custom skills from your deployment repo.

mallcop skill sign

Sign a skill directory with an SSH private key.

mallcop skill sign DIR --key ~/.ssh/id_ed25519

Produces SKILL.md.sig in the skill directory. The signature covers all files in the directory (excluding SKILL.md.sig itself). Any change to any file — including adding or removing files — invalidates the signature.

mallcop skill verify

Verify a skill directory's signature against a public key.

mallcop skill verify DIR --pubkey ~/.ssh/id_ed25519.pub [--identity author@example.com]

Exits 0 if the signature is valid, non-zero otherwise. The --identity flag overrides the identity taken from the pubkey comment field.

mallcop skill lock

Regenerate skills.lock from installed skills.

mallcop skill lock [--skills-dir DIR] [--output PATH]

Scans the skills directory for all skill subdirectories, computes SHA-256 hashes of each skill's content, and writes skills.lock. The lockfile is checked at startup in fail-closed mode — skills not in the lockfile or with changed content are not loaded. Run this after adding, updating, or removing skills, then commit skills.lock to your deployment repo.

mallcop trust add-anchor

Add an identity as a trust anchor.

mallcop trust add-anchor IDENTITY PUBKEY_FILE

Adds IDENTITY as a trust anchor using the SSH public key in PUBKEY_FILE. Anchors are the only keys that don't need endorsement — adding one is an explicit trust decision. Stored in .mallcop/trust/anchors. No-ops if the identity is already present.

mallcop trust add-key

Add an identity's public key to the keyring.

mallcop trust add-key IDENTITY PUBKEY_FILE

Adds IDENTITY to the keyring without making them an anchor. They still need to be endorsed by an anchor or an intermediary with full trust level before their skills are accepted.

mallcop trust endorse

Endorse an identity for a scope at a trust level.

mallcop trust endorse IDENTITY --scope GLOB --level full|author --expires YYYY-MM-DD --key PRIVATE_KEY [--reason TEXT] [--identity ENDORSER]

Creates a signed .endorse + .endorse.sig pair in .mallcop/trust/endorsements/. The endorsement says: "I vouch for this identity, for skills matching this scope, at this trust level, until this date." Scope narrows at each hop — an intermediary with aws-* scope cannot endorse for skills outside that scope.

mallcop trust chain

Show the trust path from an anchor to an identity.

mallcop trust chain IDENTITY [--skill SKILL_NAME]

Performs BFS from all trust anchors through the endorsement graph to find a valid path to IDENTITY for the given skill name (default: *). Exits non-zero if no trust path exists. Use this to debug trust chain issues.

mallcop trust list

Show the full trust web.

mallcop trust list

Prints the full trust state: all anchors, keyring entries, and endorsements with their scope, level, and expiry. Useful for auditing the current trust configuration. All mallcop trust subcommands accept --trust-dir to override the default trust directory (.mallcop/trust).