CmdForge

Writing YAML is useful when you want exact control. Describing the job is useful when you are still discovering the shape of the tool. forge-tool turns that description into a reviewable CmdForge configuration—and keeps ownership in the right project.

Install the Official Creator

cmdforge registry install official/forge-tool

The official tool is standalone. A clean installation does not depend on a hidden bundle of helper tools.

Create a Project-Owned Tool

cd ~/Projects/docs-intelligence

cat <<'REQUEST' | forge-tool --name docs-classify --project
Classify a bounded JSON packet of documentation excerpts. Return typed entity
candidates with source IDs and evidence offsets. Never invent an ID that was
not supplied, and allow the model to abstain.
REQUEST

The result belongs in ./.cmdforge/docs-classify/, not in the CmdForge source tree and not in another user's global configuration.

Choose Ownership Deliberately

Choice	Use it for	Location
default	Your personal cross-project commands	`~/.cmdforge/NAME/`
`--project`	Automation owned and versioned by the current repository	`./.cmdforge/NAME/`
`--output-dir PATH`	A reviewed custom tool root	The explicit path

--project and --output-dir are mutually exclusive. Existing directories and symlink targets are refused unless the explicit overwrite contract permits the operation.

Review Before You Run

cmdforge inspect docs-classify
git diff -- .cmdforge/docs-classify
sed -n '1,240p' .cmdforge/docs-classify/config.yaml
cmdforge run docs-classify --dry-run --provider mock

Generated YAML, prompts, and code are still generated code. Inspect filesystem access, subprocesses, MCP calls, provider policy, contracts, and visibility before execution or publication.

Let Reuse Earn Its Complexity

forge-tool can produce more than one tool, but decomposition is not a score. Split a component only when it has an independent purpose, a clean contract, and a plausible second caller. Keep tightly coupled transformations together.

From Project Tool to Registry Tool

cmdforge registry publish ./.cmdforge/docs-classify --dry-run
# Review the report, then publish a deliberately versioned release.

Project ownership comes first. Publication is a separate decision about reuse, documentation, security review, and long-term maintenance.

From an Idea to a Real Tool