@damper/cli

The Damper CLI prepares and checks repository context with Repomix. It creates a reviewable context proposal from a clean checkout, lets you inspect the changes, and publishes only the sections you explicitly approve. The hosted Damper MCP server remains the primary agent integration.

Older task orchestration commands were removed in this change. The CLI now exposes only the repository context commands: prepare, finalize, publish, and check.

Authentication

Set DAMPER_API_KEY to a project-scoped API key from the Damper dashboard under Settings → API Keys. The CLI continues to read existing project and global MCP credential configuration when the environment variable is not set. There is no CLI setup command in the context-only workflow.

Requirements

• Node.js ^22.13.0 or >=23.5.0
• A clean Git checkout for every context command, including the read-only check
• Claude Code installed only when using --agent claude; manual and already-running agents use --agent none or omit the flag

Usage

Install the CLI if you want to use the damper command directly, or prefix each command with npx @damper/cli:

npm install -g @damper/cli

Running the CLI without arguments prints the context command help:

npx @damper/cli

The available commands are:

damper context prepare
damper context finalize --packet <file> --proposal <file>
damper context publish --draft <file> [--yes]
damper context check [--repository-key <key>] [--max-age-days <days>] [--json]

context prepare

Start from a clean checkout. Repomix creates the source packet locally and sends it to the selected agent or provider for analysis. Damper receives only reviewed context sections and trusted preparation metadata; source files and the pack are never included in the Damper API payload.

The provider-neutral flow creates an owner-only packet and prompt for the current or another local agent:

damper context prepare
# Read the owner-only packet and prompt, then write a proposal JSON file
damper context finalize --packet "/tmp/.../packet.json" --proposal "/tmp/.../proposal.json"
damper context publish --draft "/tmp/.../publish-draft.json"

To launch the installed Claude CLI in restricted print mode instead, pass --agent claude:

damper context prepare --agent claude
# Review the printed publish-draft.json path
damper context publish --draft "/tmp/.../publish-draft.json"

--agent none is an explicit spelling of the provider-neutral flow. --repository-key, repeated --include, and repeated --ignore select the repository identity and source scope. A stable scope can be committed in .damper/context.json:

{
  "repositoryKey": "default",
  "include": ["server/**", "packages/**", "README.md"],
  "ignore": ["**/fixtures/generated/**"]
}

context finalize

Use this when an external or already-running agent reviewed the packet. The CLI validates the proposal and attaches trusted Git revision, source fingerprint, source file count, scope, context versions, and receipt baseline metadata. The agent can propose section content but cannot choose those values.

damper context finalize \
  --packet "/tmp/.../packet.json" \
  --proposal "/tmp/.../proposal.json"

context publish

Publishing first requests a server-side preview. Review every created, updated, and unchanged section, including content, tags, appliesTo, and critical rules. Confirm the publish explicitly; use --yes only after a separate review step.

Publication is atomic and version guarded. A concurrent context edit, stale receipt, or changed section hash rejects the whole draft without a partial write. Omitted sections remain unchanged. Repeating the same request is idempotent and returns the original receipt.

damper context publish --draft "/tmp/.../publish-draft.json"

context check

The freshness check is deterministic, read-only, and makes no model call. It exits nonzero when no receipt exists, selected file contents differ, managed context changed, or the receipt is older than the configured maximum age. A different commit SHA with identical selected contents remains fresh.

damper context check
damper context check --repository-key default --max-age-days 30 --json

Use it manually, after a substantial default-branch merge, or as a downstream deployment/release gate. Refresh from the merged checkout, review and publish the new proposal, then rerun the check. Do not publish feature-branch guidance before that branch is merged.

An opt-in default-branch and scheduled example is available at examples/context-refresh.github.yml. Pin the CLI version used by the workflow and make deployment depend on the check job.

Security and scope

Damper always adds strict ignores for secrets, credentials, dependency trees, generated output, binary assets, lockfiles, and local .damper state. Repomix configuration files in the target repository are never loaded or executed. Packing keeps full source by default and disables compression for behavior analysis. Large selections fail with guidance to narrow the include scope instead of silently dropping files.

The generated pack, prompt, packet, proposal, and draft remain in an owner-readable temporary directory outside the repository. Every context command rejects a dirty or changed checkout, including the read-only check. The agent must never include secrets, credentials, environment values, source-code bodies, or the analysis prompt in a context proposal.

Contextual MCP guidance

MCP context responses may include optional repository freshness guidance. A missing receipt can suggest setup; known managed context edits or deletions can suggest the read-only check and a reviewed refresh; healthy receipts stay silent. MCP cannot inspect the checkout or source, so run damper context check locally. Hints never publish or rewrite context automatically.

Further reading

• MCP documentation
• Damper documentation