|
|
|
@@ -6,6 +6,133 @@ part of the book while retaining the established editorial voice.
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
MODERN_DOCS = {
|
|
|
|
|
"installation": {
|
|
|
|
|
"title": "Installation",
|
|
|
|
|
"description": "Install CmdForge, discover an AI provider, and verify the command line",
|
|
|
|
|
"parent": "getting-started",
|
|
|
|
|
"content": """
|
|
|
|
|
<p class="lead">CmdForge runs on Python 3.10 or newer. The command-line tools and desktop builder
|
|
|
|
|
install together; optional extras add MCP, interactive PTY providers, and the registry web stack.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="pipx">A Clean Personal Installation</h2>
|
|
|
|
|
<p><code>pipx</code> keeps CmdForge isolated while placing <code>cmdforge</code> and <code>cf</code> on
|
|
|
|
|
your path:</p>
|
|
|
|
|
<pre><code class="language-bash">pipx install 'cmdforge[all]'
|
|
|
|
|
cmdforge --version
|
|
|
|
|
cmdforge --help</code></pre>
|
|
|
|
|
<p>A normal virtual environment works just as well:</p>
|
|
|
|
|
<pre><code class="language-bash">python3.10 -m venv .venv
|
|
|
|
|
. .venv/bin/activate
|
|
|
|
|
python -m pip install 'cmdforge[all]'</code></pre>
|
|
|
|
|
|
|
|
|
|
<h2 id="extras">Choose Only the Extras You Need</h2>
|
|
|
|
|
<table class="w-full my-5"><thead class="bg-gray-100"><tr><th>Install</th><th>Adds</th></tr></thead><tbody>
|
|
|
|
|
<tr class="border-b"><td><code>cmdforge</code></td><td>CLI, desktop GUI, contracts, registry client, and local tool runner</td></tr>
|
|
|
|
|
<tr class="border-b"><td><code>cmdforge[mcp]</code></td><td>MCP client steps and MCP server integration</td></tr>
|
|
|
|
|
<tr class="border-b"><td><code>cmdforge[pty]</code></td><td>Interactive pseudo-terminal providers</td></tr>
|
|
|
|
|
<tr><td><code>cmdforge[all]</code></td><td>All optional runtime features, including the web stack</td></tr>
|
|
|
|
|
</tbody></table>
|
|
|
|
|
|
|
|
|
|
<h2 id="provider">Let CmdForge Inspect the Machine</h2>
|
|
|
|
|
<pre><code class="language-bash">cmdforge providers discover
|
|
|
|
|
cmdforge providers discover --add
|
|
|
|
|
cmdforge providers list</code></pre>
|
|
|
|
|
<p>Discovery recognizes supported coding CLIs, API-key environment variables, and Ollama models.
|
|
|
|
|
The built-in <code>mock</code> provider lets you test structure before authenticating a real engine.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="smoke-test">Run a Smoke Test</h2>
|
|
|
|
|
<pre><code class="language-bash">cmdforge create hello --prompt "Reply with a short greeting to {input}"
|
|
|
|
|
echo "Ada" | cmdforge run hello --provider mock
|
|
|
|
|
cmdforge inspect hello</code></pre>
|
|
|
|
|
<p>If wrapper commands are not on your shell path, add <code>~/.local/bin</code> or run the explicit
|
|
|
|
|
<code>cmdforge run NAME</code> form.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="development">Install for Development</h2>
|
|
|
|
|
<pre><code class="language-bash">git clone https://gitea.brrd.tech/rob/CmdForge.git
|
|
|
|
|
cd CmdForge
|
|
|
|
|
python -m pip install -e '.[all,dev]'
|
|
|
|
|
pytest tests/ -m "not integration"</code></pre>
|
|
|
|
|
<p>Continue with <a href="/docs/first-tool">Your First Tool</a>, or connect a coding host through
|
|
|
|
|
<a href="/docs/mcp-overview">MCP</a>.</p>
|
|
|
|
|
""",
|
|
|
|
|
"headings": [
|
|
|
|
|
("pipx", "A Clean Personal Installation"),
|
|
|
|
|
("extras", "Choose Only the Extras You Need"),
|
|
|
|
|
("provider", "Inspect the Machine"),
|
|
|
|
|
("smoke-test", "Run a Smoke Test"),
|
|
|
|
|
("development", "Install for Development"),
|
|
|
|
|
],
|
|
|
|
|
},
|
|
|
|
|
|
|
|
|
|
"provider-setup": {
|
|
|
|
|
"title": "Provider Setup",
|
|
|
|
|
"description": "Discover and verify local models, coding CLIs, and compatible APIs",
|
|
|
|
|
"parent": "providers",
|
|
|
|
|
"content": """
|
|
|
|
|
<p class="lead">Provider setup is an inventory, not a pledge of allegiance. Add the engines already
|
|
|
|
|
available to you, describe their real trust boundaries, and choose among them per tool or per run.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="discover">Discover Before Installing More Software</h2>
|
|
|
|
|
<pre><code class="language-bash">cmdforge providers discover
|
|
|
|
|
cmdforge providers discover --add
|
|
|
|
|
cmdforge providers check</code></pre>
|
|
|
|
|
<p>CmdForge looks for supported CLIs on <code>PATH</code>, known API-key environment variables, and
|
|
|
|
|
models reported by a local Ollama installation. It never prints the values of discovered API keys.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="desktop">Use the Desktop Installer</h2>
|
|
|
|
|
<ol>
|
|
|
|
|
<li>Launch <code>cmdforge</code>.</li>
|
|
|
|
|
<li>Open <strong>Providers</strong> in the sidebar.</li>
|
|
|
|
|
<li>Choose <strong>Install Provider…</strong> to see available and already installed groups.</li>
|
|
|
|
|
<li>Review the external installation instructions, then select the provider variants to add.</li>
|
|
|
|
|
<li>Return to the Providers page and test the saved entry.</li>
|
|
|
|
|
</ol>
|
|
|
|
|
<p>The GUI and CLI edit the same <code>~/.cmdforge/providers.yaml</code> file.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="terminal">Use the Terminal Installer</h2>
|
|
|
|
|
<pre><code class="language-bash">cmdforge providers install</code></pre>
|
|
|
|
|
<p>The interactive guide detects what is already present, shows installation instructions for what
|
|
|
|
|
is missing, and offers maintained provider variants. Since external CLIs change independently,
|
|
|
|
|
read the displayed command before approving it.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="ollama">A Local-First Starting Point</h2>
|
|
|
|
|
<p>Ollama is a useful choice when material must stay on the computer. After installing Ollama with
|
|
|
|
|
its official instructions and pulling a model, let CmdForge discover the exact model:</p>
|
|
|
|
|
<pre><code class="language-bash">ollama list
|
|
|
|
|
cmdforge providers discover --add
|
|
|
|
|
cmdforge providers list</code></pre>
|
|
|
|
|
<p>A provider being local is a declared fact you should verify. For sensitive work, enforce it at
|
|
|
|
|
runtime with <code>--require-local --no-fallback</code>.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="api">Add an OpenAI-Compatible API</h2>
|
|
|
|
|
<pre><code class="language-bash">export RESEARCH_API_KEY="..."
|
|
|
|
|
|
|
|
|
|
cmdforge providers add research-api https://api.example.com/v1 \
|
|
|
|
|
--type api --model research-model \
|
|
|
|
|
--api-key-env RESEARCH_API_KEY --locality remote \
|
|
|
|
|
--capability text --capability structured-json \
|
|
|
|
|
--data-policy public</code></pre>
|
|
|
|
|
<p>Only the environment variable name is stored. Keep the key in your normal credential mechanism,
|
|
|
|
|
not in <code>providers.yaml</code>.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="verify">Test and Inspect</h2>
|
|
|
|
|
<pre><code class="language-bash">cmdforge providers test research-api
|
|
|
|
|
cmdforge providers list
|
|
|
|
|
cmdforge providers for-tools summarize classify-text</code></pre>
|
|
|
|
|
<p>Testing confirms availability and a basic response. It does not prove privacy, semantic quality,
|
|
|
|
|
or model identity. Record those facts explicitly and use the strict controls in
|
|
|
|
|
<a href="/docs/provider-policy">Provider Policy and Provenance</a>.</p>
|
|
|
|
|
""",
|
|
|
|
|
"headings": [
|
|
|
|
|
("discover", "Discover Before Installing"),
|
|
|
|
|
("desktop", "Use the Desktop Installer"),
|
|
|
|
|
("terminal", "Use the Terminal Installer"),
|
|
|
|
|
("ollama", "A Local-First Starting Point"),
|
|
|
|
|
("api", "Add a Compatible API"),
|
|
|
|
|
("verify", "Test and Inspect"),
|
|
|
|
|
],
|
|
|
|
|
},
|
|
|
|
|
|
|
|
|
|
"mcp-overview": {
|
|
|
|
|
"title": "MCP: Tools Without Islands",
|
|
|
|
|
"description": "Connect CmdForge to the Model Context Protocol in both directions",
|
|
|
|
|
