commands.md

Commands

This document explains the core chumdump commands and what each one reads or writes.

chumdump init

Creates a chumdump project. The command writes chumdump.yaml, creates the bait, dump, report, and state directories, and prepares the local indexes that other commands use.

chumdump init ai-crawler-test

Use --name to set a project name that differs from the directory name. Use --force to replace an existing chumdump.yaml.

chumdump bait create

Creates one chumbait artifact and records it in the project bait index. The generated file is written under the configured bait directory.

chumdump bait create --type canary --name violet-harbor

Supported bait types include canary, crawler-bait, prompt-trap, rag-bait, fake-secret, watermark, lore-seed, and decoy-doc. Use --target to describe the test context, such as agent, crawler, or rag.

chumdump bait create --type prompt-trap --target agent

chumdump bait list

Lists bait artifacts that have been created in the current project. This is useful before building a dump so you can see which bait IDs, types, and names are available.

chumdump bait list

Use --json when another tool needs machine-readable output.

chumdump dump build

Builds a deployable chumdump bundle from existing bait. If the project does not yet have enough bait for the requested count, the command generates additional bait that matches the selected profile.

chumdump dump build --profile website --count 8

Profiles include website, rag-test, and agent-trap. A dump contains copied bait files, manifest.json, index.html, and robots.txt.

chumdump dump create

Alias for chumdump dump build. Use it when "create a dump" reads more naturally in a workflow.

chumdump dump create --profile rag-test --count 50

chumdump deploy

Copies a built dump into an owned destination, such as a website public folder or test corpus directory. By default, it deploys the latest dump.

chumdump deploy ./public

Use --dump to deploy a specific dump ID or unique prefix. Use --force to overwrite destination files that already exist. The command writes a .chumdump-deploy.json marker so cleanup can remove the files later.

chumdump scan

Scans a file or directory for chumdump markers. It can identify known project bait, generic CHUM- markers, fake secret markers, and dump manifests.

chumdump scan ./public

Use --json to return structured findings.

chumdump watch

Parses access logs and records bite events when a log line mentions a known bait ID, bait filename, or canary marker. It also labels known AI crawlers from user-agent strings when possible.

chumdump watch --logs ./access.log

The command supports JSONL-style logs and common web access log lines. Detected bites are classified as accessed, retrieved, echoed, obeyed, leaked, or unknown, then appended to the project bite log.

chumdump bites

Shows recorded bite events for the current project, including the bite type. Use this after chumdump watch to review what touched the bait.

chumdump bites

Use --type to filter by accessed, retrieved, echoed, obeyed, leaked, or unknown.

chumdump bites --type echoed

Use --json for machine-readable bite records. The filter applies to JSON output too.

chumdump report

Generates an evidence report from project bait, dumps, deployments, and recorded bites. Reports include bite type, actor, placement, and supporting evidence.

chumdump report --format markdown

Supported formats are markdown, json, html, and sarif. Use --output to choose the destination path, or --stdout to print the report instead of writing a file.

chumdump cleanup

Removes files from a previous deployment by reading the destination's .chumdump-deploy.json marker.

chumdump cleanup ./public

This command removes only files recorded in the deployment marker and then removes empty directories left behind by that deployment.