Grace Cli

Use the optional grace CLI as a fast GRACE-aware read/query layer.

Prerequisites

• The grace binary must be installed and available on PATH
• The target repository should already use GRACE artifacts and markup
• Prefer --path unless you are already in the project root

If the CLI is missing, or the repository is not a GRACE project, say so and fall back to reading the relevant docs and code directly.

Choose the Right Command

• grace lint --path

Use for a fast integrity snapshot across semantic markup, XML artifacts, and export/map drift.

• grace lint --profile autonomous --path

Use before long agent runs to verify that operational packets, verification entries, and observable evidence are strong enough for autonomous execution.

• grace lint --explain

Use when a lint code appears in CI or review and you want the built-in explanation plus remediation guidance.

• grace status --path

Use for a one-shot health report: artifact presence, codebase metrics, integrity snapshot, autonomy gate, recent changes, and the next safe action.

• grace status --with modules --path

Use when you also want per-module health summaries in the same report.

• grace module find --path

Use to resolve module IDs from names, paths, dependencies, annotations, verification refs, or file-local LINKS.

• grace module show --path

Use to read the shared/public module view from development-plan.xml, knowledge-graph.xml, implementation steps, and linked files.

• grace module show --with verification --path

Use when you also need the module's verification excerpt.

• grace module health --path

Use for one module's implementation coverage, verification health, autonomy readiness, blockers, and next action.

• grace verification find --path

Use to search verification entries by ID, module, priority, scenarios, test files, log markers, or commands.

• grace verification show --path

Use to read one verification entry with its linked module context.

• grace file show --path

Use to read file-local/private MODULE_CONTRACT, MODULE_MAP, and CHANGE_SUMMARY.

• grace file show --contracts --blocks --path

Use when you also need function/type contracts and semantic block navigation.

Recommended Workflow

Use grep or exact-text search first when the target is still broad, then use the CLI for the narrowed shared/public and file-local/private views.

Canonical anchors to search for when narrowing scope:

• M- for module IDs
• V-M- for verification IDs
• CrossLink for graph edges
• START_MODULE_CONTRACT
• START_MODULE_MAP
• START_CONTRACT:
• START_BLOCK_
• START_CHANGE_SUMMARY
• LINKS:

Copy-paste grep recipes:

grep -R -n -E '\bM-[A-Z0-9]+(-[A-Z0-9]+)*\b' docs/development-plan.xml docs/knowledge-graph.xml
grep -R -n -E '\bV-M-[A-Z0-9]+(-[A-Z0-9]+)*\b' docs/verification-plan.xml docs/knowledge-graph.xml
grep -R -n 'LINKS:' src tests
grep -R -n 'START_MODULE_CONTRACT\|START_MODULE_MAP\|START_CHANGE_SUMMARY' src tests
grep -R -n 'START_CONTRACT:\|START_BLOCK_' src tests
grep -R -n 'M-XXX' docs src tests
grep -R -n 'V-M-XXX\|M-XXX' docs src tests

Normalization rules:

• assume module IDs use exact M- form
• assume verification IDs use exact V-M- form
• assume field labels and anchor prefixes are canonical and should not be aliased

1. Run grace status when you first need to understand the current project state.
2. Run grace status --with modules when project-level health is not enough and you need module summaries.
3. Run grace lint when integrity or drift matters.
4. Run grace lint --profile autonomous before long autonomous execution.
5. Run grace lint --explain when one issue needs targeted remediation guidance.
6. Use grep or exact-text search to narrow the target module, verification entry, file path, or semantic anchor.
7. Run grace module find to resolve the target module from the user's words, a stack trace, or a changed path.
8. Run grace module show, grace module health, and grace verification show for the narrowed shared/public truth.
9. Run grace file show for the file-local/private truth.
10. Read the underlying XML or source files only for the narrowed scope that still needs deeper evidence.

Output Guidance

• Use default text output for quick review and direct user-facing summaries.
• Use --json when another tool, script, or agent step needs machine-readable output.
• Use --fail-on warnings or --fail-on errors when the CLI output should gate CI.
• Treat CLI output as navigation help, not as a replacement for the real XML and source files when exact evidence is required.

Public/Private Rule

• grace module show is for shared/public module context.
• grace file show is for file-local/private implementation context.
• If shared docs and file-local markup disagree, call out the drift instead of silently trusting one side.

Important

• The CLI is a companion to the GRACE skills, not a replacement for them.
• Prefer this skill when the task is to inspect, navigate, or lint a GRACE project quickly through the CLI.
• For methodology design, execution planning, refresh, review, or fixes, route to the appropriate grace-* skill after using the CLI to narrow scope.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: osovv
• Source: osovv/grace-marketplace
• License: MIT

Install and usage instructions live in the source repository linked above.