Metadata-Version: 2.4
Name: cmdforge
Version: 0.2.0
Summary: Build, compose, and share AI-powered command-line tools you own
Author: Rob
License-Expression: MIT
Project-URL: Homepage, https://cmdforge.brrd.tech
Project-URL: Documentation, https://cmdforge.brrd.tech/docs
Project-URL: Repository, https://gitea.brrd.tech/rob/CmdForge.git
Project-URL: Issues, https://gitea.brrd.tech/rob/CmdForge/issues
Project-URL: Changelog, https://gitea.brrd.tech/rob/CmdForge/src/branch/main/CHANGELOG.md
Keywords: ai,cli,tools,automation,llm,terminal,unix,pipe
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests>=2.28
Requires-Dist: PySide6>=6.5
Requires-Dist: NodeGraphQt>=0.6.0
Requires-Dist: setuptools
Requires-Dist: jsonschema>=4.0
Requires-Dist: cryptography>=41.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: tomli>=1.1; python_version < "3.11" and extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=6.0; extra == "release"
Provides-Extra: registry
Requires-Dist: Flask>=2.3; extra == "registry"
Requires-Dist: argon2-cffi>=21.0; extra == "registry"
Requires-Dist: sentry-sdk[flask]>=1.0; extra == "registry"
Requires-Dist: gunicorn>=21.0; extra == "registry"
Provides-Extra: flow
Requires-Dist: NodeGraphQt-QuiltiX-fork[pyside6]>=0.7.0; extra == "flow"
Requires-Dist: setuptools; extra == "flow"
Provides-Extra: pty
Requires-Dist: pexpect>=4.8; extra == "pty"
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.27; extra == "mcp"
Provides-Extra: all
Requires-Dist: Flask>=2.3; extra == "all"
Requires-Dist: argon2-cffi>=21.0; extra == "all"
Requires-Dist: sentry-sdk[flask]>=1.0; extra == "all"
Requires-Dist: gunicorn>=21.0; extra == "all"
Requires-Dist: NodeGraphQt-QuiltiX-fork[pyside6]>=0.7.0; extra == "all"
Requires-Dist: setuptools; extra == "all"
Requires-Dist: pexpect>=4.8; extra == "all"
Requires-Dist: mcp<2,>=1.27; extra == "all"
Dynamic: license-file

# CmdForge

**Turn useful AI workflows into commands you own.**

CmdForge is a personal tool-building environment for the command line. A tool
can combine prompts, Python, other CmdForge tools, and Model Context Protocol
(MCP) calls, then behave like an ordinary Unix command:

```bash
cat meeting.txt | meeting-decisions
git diff --staged | review-change
cmdforge run classify-private --no-fallback --require-local
```

Tools are readable YAML, stored either in `~/.cmdforge/` for personal use or
`./.cmdforge/` when they belong to a project. You choose the provider at build
time or runtime: a local Ollama model, an installed coding CLI, or an
OpenAI-compatible API.

## Install

CmdForge requires Python 3.10 or newer. `pipx` is recommended for a personal
command-line application:

```bash
pipx install "cmdforge[mcp,pty]"
```

Or install it in a virtual environment:

```bash
python -m pip install "cmdforge[mcp,pty]"
```

The base `cmdforge` package includes the CLI and desktop tool builder. The
`mcp` extra adds MCP client/server support, while `pty` adds interactive CLI
providers.

Verify the installation and discover providers already present on the machine:

```bash
cmdforge --version
cmdforge providers discover
cmdforge providers discover --add
```

## Begin with One Useful Command

```bash
cmdforge create explain --prompt "Explain this clearly for a beginner: {input}"
echo "def area(r): return 3.14159 * r * r" | cmdforge run explain
```

Use the deterministic mock provider while developing:

```bash
echo "sample input" | cmdforge run explain --provider mock
cmdforge inspect explain
```

For AI-assisted creation, install CmdForge's official `forge-tool`:

```bash
cmdforge registry install official/forge-tool

echo "Create a tool that extracts decisions and owners from meeting notes" \
  | forge-tool --name meeting-decisions --project
```

## Four Kinds of Step

- **Prompt steps** call a selected AI provider.
- **Code steps** perform deterministic Python transformations.
- **Tool steps** compose existing CmdForge tools and delegated contexts.
- **MCP steps** call tools exposed by external MCP servers.

Contracts, deterministic preflight, regression baselines, schema compatibility,
and evidence-based quality scores help distinguish “worked once” from a tool
you can maintain.

## Use CmdForge from Coding Agents

CmdForge can act as an MCP server for Codex and Claude Code. It is closed by
default: configuring a host does not expose any tools until you add an explicit
allowlist to `~/.cmdforge/mcp.yaml`.

```bash
cmdforge mcp configure codex --dry-run
cmdforge mcp configure codex

cmdforge mcp configure claude-code --scope project --dry-run
```

Agents can also discover the local and remote catalogs without reading prompt
or code bodies:

```bash
cmdforge list --json --filter "commit message" --limit 10
cmdforge registry search "release notes" --json --limit 5
git diff | cmdforge run-once "Summarize this change: {input}"
```

## Privacy and Provenance

Fallback is a data-movement decision. Sensitive callers can require a local
provider, particular capabilities, and verified runtime identity:

```bash
cmdforge run incident-summary \
  --provider local-reasoner \
  --no-fallback \
  --require-local \
  --require-capability structured-json \
  --data-classification private \
  --require-model-identity \
  --result-envelope json
```

The result envelope reports the requested provider, actual provider, attempted
fallback chain, model, digest, and locality. Those fields are produced by
CmdForge rather than invented by the model.

## Learn More

- [Documentation](https://cmdforge.brrd.tech/docs)
- [MCP and coding agents](https://cmdforge.brrd.tech/docs/mcp-overview)
- [Providers and privacy policy](https://cmdforge.brrd.tech/docs/providers)
- [Contracts and quality evidence](https://cmdforge.brrd.tech/docs/contracts-quality)
- [Registry](https://cmdforge.brrd.tech/tools)
- [Source and issues](https://gitea.brrd.tech/rob/CmdForge)

CmdForge is beta software, distributed under the MIT License. Review generated
tools and third-party registry tools as you would any other executable code.
