Quickstart

This walkthrough assumes you have installed the CLI and have project-local agent files to review. Run every command from the project root: the CLI does not search parent directories for seal.json.

1. Review the files

Start with an existing skill directory such as .agents/skills/code-review/. Inspect its instructions, scripts, and other resources before pinning. Seal records file contents; it does not determine whether those contents are safe.

2. Bootstrap seal.json

seal init

The CLI proposes discovery patterns for known agent directories that exist in your project, shows a summary, and asks for confirmation. For example, an existing .agents/skills/ directory produces .agents/skills/*: each regular-file child or non-empty directory child becomes a bundle, and directory bundles are hashed recursively.

Inspect the proposed paths before confirming. init writes seal.json with the default block policy and refuses to overwrite an existing lockfile. If it finds no known layouts, it offers to create an empty lockfile. An empty lockfile does not cover your agent files until you add paths.

Review and commit the generated lockfile through your normal approval process:

git diff --no-index /dev/null seal.json
git add seal.json
git commit -m "Add Seal lockfile"

The inspection command exits 1 when it shows differences; that is normal for git diff. Commit newly added agent files as well if your project tracks them in Git.

3. Check coverage

Open seal.json and inspect discovery and bundles. Initialization only proposes known directories present at that time. It does not guarantee coverage of every path your agent can load.

To include an existing reviewed file outside those directories:

seal pin prompts/review.md

Targeted pin adds the named file and an exact discovery pattern if needed. That checks prompts/review.md, but it does not detect a new sibling such as prompts/deploy.md.

To check each direct Markdown file in that directory and detect new siblings, set the discovery pattern to prompts/*.md, then run seal pin and review its proposed changes. A directory root and its child file roots cannot both be recorded. Switching to a whole-directory bundle requires replacing the existing file entries and discovery patterns; see bundle boundaries.

4. Verify

seal verify

Verification is read-only, offline, and never prompts. It compares the current files with the lockfile and applies its policy.

Exit	Meaning
0	Verified, Drift, or Warning. The command permits the pipeline to continue under the configured policy.
1	Blocked: a mismatch or unpinned bundle was found under block.
2	A fatal configuration or system error, including a missing or invalid lockfile.

For example, with .agents/skills/* in discovery:

Change since pinning	Result under block
Edit code-review/SKILL.md or add a script inside that bundle	Mismatch; exit 1.
Add a new non-empty .agents/skills/deploy/ directory	Unverified; exit 1.
Delete a file inside the still-present code-review/ directory	Mismatch; exit 1.
Delete the entire code-review/ directory	Removed; overall Drift and exit 0 if no other issues exist.

See the complete change-scenario tables for moves, renames, deleted roots, new files, coverage gaps, and filesystem edge cases. The policy table shows how multiple states combine.

Use seal verify --json for structured results, or seal verify --quiet for an exit code only. Those two flags are mutually exclusive. Under warn, mismatches and new bundles produce Warning and exit 0.

5. Wire it into CI

After installing Seal in the job, add:

- name: Verify Seal lockfile
  run: seal verify --quiet

Run verification after preparing the bundle files and before any pipeline step that uses them. Make its nonzero exit fail the job. See CI / CD integration for full examples and guidance on protecting lockfile changes.

This checks the CI checkout at that moment. It does not intercept local agent loads or protect files changed after verification; load-time enforcement needs native agent integration.

6. Handle an intentional update

Review the changed instructions and scripts first. Inspect newly added files too; they may not appear in an ordinary Git diff.

# After reviewing the actual content changes:
seal pin .agents/skills/code-review

# Review the updated snapshot and check the result:
git diff -- seal.json
seal verify

Pinning shows a summary and requires interactive confirmation when changes are pending. There is no -y or --force bypass. Review and commit the source changes and lockfile together.

Bulk seal pin proposes updates for all recorded and discovered bundles. It retains missing bundle entries. seal pin --prune also drops missing entries and can re-pin other changed bundles in the same operation, so review the entire proposal.

The workflow is:

review content changes → seal pin → review lockfile diff → commit → verify in CI

A matching lockfile is an integrity baseline, not proof that a change was approved. Your repository review and access controls establish that trust.