From cdc910d7b62e72cd46d4775685fffef4da7f7092 Mon Sep 17 00:00:00 2001 From: rob Date: Sun, 18 Jan 2026 00:54:36 -0400 Subject: [PATCH] Add comprehensive documentation for Collections, Project Dependencies, Provider Setup, and CLI Reference - Add Tool Collections tutorial covering bundles, installation, and creating collections - Add Project Dependencies tutorial for cmdforge.yaml manifests and team workflows - Add Provider Setup guide with interactive installer and testing commands - Add complete CLI Reference for all commands - Update TOC with new sections Co-Authored-By: Claude Opus 4.5 --- src/cmdforge/web/docs_content.py | 927 ++++++++++++++++++++++++++++++- 1 file changed, 925 insertions(+), 2 deletions(-) diff --git a/src/cmdforge/web/docs_content.py b/src/cmdforge/web/docs_content.py index b246b4d..1f3a760 100644 --- a/src/cmdforge/web/docs_content.py +++ b/src/cmdforge/web/docs_content.py @@ -3230,6 +3230,923 @@ providers: ("next", "Next Steps"), ], }, + + "collections": { + "title": "Tool Collections", + "description": "Install curated bundles of tools with a single command", + "content": """ +

Why install tools one at a time? Collections are curated bundles of tools that work +great together. One command gives you a complete toolkit for a specific workflow—whether you're +a developer, writer, or data wrangler.

+ +
+

What You'll Learn

+
    +
  • What collections are and why they're useful
    • +
  • Browsing available collections
    • +
  • Installing a complete toolkit in one command
    • +
  • Understanding pinned versions
    • +
+
+ +

What Are Collections?

+ +

Think of collections like playlists for your terminal. Someone has already done the work of finding +tools that complement each other, testing them together, and bundling them up. You just hit play.

+ +
+
+
🎯
+

Curated

+

Hand-picked tools that work well together

+
+
+
⚡
+

One Command

+

Install everything at once

+
+
+
🔒
+

Version Pinned

+

Tested versions that work together

+
+
+ +

Browsing Collections

+ +

See what's available:

+ +
# List all collections
+cmdforge collections list
+ +

You'll see something like:

+ +
Available collections (4):
+
+  starter
+    The Starter Pack
+    Essential tools for getting started with CmdForge
+    Tools: 5
+
+  developer
+    Developer Toolkit
+    Code review, testing, and documentation tools
+    Tools: 8
+
+  writer
+    Writer's Workshop
+    Grammar, tone, and content tools for writers
+    Tools: 6
+
+  data
+    Data Wrangler
+    JSON, CSV, and data extraction tools
+    Tools: 7
+
+Install a collection with: cmdforge collections install
+ +

Viewing Collection Details

+ +

Before installing, see exactly what you'll get:

+ +
# See what's in a collection
+cmdforge collections info starter
+ +

Output:

+ +
The Starter Pack
+==================================================
+
+Essential tools for getting started with CmdForge.
+Perfect for new users who want a solid foundation.
+
+Maintainer: official
+Tags: beginner, essential, getting-started
+
+Tools (5):
+  - official/summarize
+  - official/translate
+  - official/fix-grammar
+  - official/explain-error
+  - official/commit-msg
+
+Install all: cmdforge collections install starter
+ +

Installing a Collection

+ +

Ready to go? One command:

+ +
# Install all tools in a collection
+cmdforge collections install starter
+ +

Watch as each tool is downloaded and installed:

+ +
Installing collection: The Starter Pack
+Tools to install: 5
+
+  Installing official/summarize... v1.2.0
+  Installing official/translate... v1.1.0
+  Installing official/fix-grammar... v1.0.3
+  Installing official/explain-error... v1.1.2
+  Installing official/commit-msg... v2.0.0
+
+Installed: 5/5
+
+Collection 'starter' installed successfully!
+ +

All five tools are now available as commands. Try them:

+ +
echo "teh quick brown fox" | fix-grammar
+# The quick brown fox
+ +

Pinned Versions

+ +

Collections can pin specific versions of tools that are known to work well together. Use the +--pinned flag to install these exact versions:

+ +
# Install with pinned (tested) versions
+cmdforge collections install developer --pinned
+ +

This is useful when you need reproducible setups across machines or team members.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CollectionDescriptionTools
starterEssential tools for beginnerssummarize, translate, fix-grammar, explain-error, commit-msg
developerCode review and development toolsreview-code, explain-code, gen-tests, docstring, plus more
writerContent creation and editingfix-grammar, tone-shift, simplify, expand, eli5, tldr
dataData extraction and transformationjson-extract, json2csv, extract-emails, csv-insights, sql-from-text
+ +

Next Steps

+ + +""", + "headings": [ + ("what-are-collections", "What Are Collections?"), + ("browsing", "Browsing Collections"), + ("collection-details", "Viewing Collection Details"), + ("installing", "Installing a Collection"), + ("pinned-versions", "Pinned Versions"), + ("popular-collections", "Popular Collections"), + ("next", "Next Steps"), + ], + }, + + "project-deps": { + "title": "Project Dependencies", + "description": "Lock tool versions for reproducible team workflows", + "content": """ +

Working on a project with a team? Need the same tools on your CI server? +Project dependencies let you declare which tools your project needs, pin their versions, +and install everything with a single command. Think package.json for your AI tools.

+ +
+

What You'll Learn

+
    +
  • Creating a cmdforge.yaml manifest
    • +
  • Adding and managing dependencies
    • +
  • Version constraints and pinning
    • +
  • Installing dependencies for your project
    • +
  • Overriding providers for different environments
    • +
+
+ +

Why Project Dependencies?

+ +

Without dependency management:

+ + + +

With cmdforge.yaml:

+ + + +

Creating a Manifest

+ +

Initialize a new manifest in your project:

+ +
# Create cmdforge.yaml in current directory
+cmdforge init
+
+# With custom project name and version
+cmdforge init --name my-project --version 1.0.0
+ +

This creates a cmdforge.yaml file:

+ +
name: my-project
+version: 1.0.0
+dependencies: []
+ +

Adding Dependencies

+ +

Add tools your project needs:

+ +
# Add a tool (installs it too)
+cmdforge add official/summarize
+
+# Add with version constraint
+cmdforge add official/translate --version "^1.0.0"
+
+# Add without installing (just record it)
+cmdforge add official/fix-grammar --no-install
+ +

Your manifest now looks like:

+ +
name: my-project
+version: 1.0.0
+dependencies:
+  - name: official/summarize
+    version: "*"
+  - name: official/translate
+    version: "^1.0.0"
+  - name: official/fix-grammar
+    version: "*"
+ +

Version Constraints

+ +

Control which versions are acceptable:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConstraintMeaningExample Matches
*Any version (latest)1.0.0, 2.0.0, 3.5.2
1.2.3Exact version only1.2.3
^1.2.0Compatible (same major)1.2.0, 1.3.0, 1.9.9
~1.2.0Approximate (same minor)1.2.0, 1.2.1, 1.2.9
>=1.0.0At least this version1.0.0, 1.5.0, 2.0.0
<2.0.0Before this version1.0.0, 1.9.9
+ +
+

Recommendation

+

Use ^1.0.0 (caret) for most dependencies. This allows + bug fixes and new features while preventing breaking changes.

+
+ +

Installing Dependencies

+ +

When someone clones your project:

+ +
# Install all dependencies from cmdforge.yaml
+cmdforge install
+ +

This reads the manifest, resolves versions, and installs every tool. Perfect for:

+ + + +

Checking Dependencies

+ +

See what's in your manifest and what's installed:

+ +
# Show project dependencies
+cmdforge deps
+ +

Output:

+ +
Project: my-project v1.0.0
+
+Dependencies (3):
+  ✓ official/summarize    * (installed: 1.2.0)
+  ✓ official/translate    ^1.0.0 (installed: 1.1.0)
+  ✗ official/fix-grammar  * (not installed)
+
+Run 'cmdforge install' to install missing dependencies.
+ +

Provider Overrides

+ +

Need to use different AI providers in different environments? Add overrides to your manifest:

+ +
name: my-project
+version: 1.0.0
+dependencies:
+  - name: official/summarize
+    version: "^1.0.0"
+
+overrides:
+  summarize:
+    provider: ollama    # Use local Ollama instead of cloud
+ +

This is useful for:

+ + + +

Manifest Location

+ +

CmdForge searches for cmdforge.yaml starting from your current directory and +moving up to parent directories. This means you can have:

+ + + +

Recommended Workflow

+ +
+
    +
  1. 1. Initialize - cmdforge init in your project root
    2. +
  2. 2. Add tools - cmdforge add owner/tool as you need them
    3. +
  3. 3. Commit - Add cmdforge.yaml to version control
    4. +
  4. 4. Document - Tell your team to run cmdforge install
    5. +
  5. 5. CI/CD - Add cmdforge install to your pipeline
    6. +
+
+ +

Next Steps

+ + +""", + "headings": [ + ("why", "Why Project Dependencies?"), + ("creating", "Creating a Manifest"), + ("adding-deps", "Adding Dependencies"), + ("version-constraints", "Version Constraints"), + ("installing-deps", "Installing Dependencies"), + ("checking-deps", "Checking Dependencies"), + ("overrides", "Provider Overrides"), + ("manifest-location", "Manifest Location"), + ("workflow", "Recommended Workflow"), + ("next", "Next Steps"), + ], + }, + + "provider-setup": { + "title": "Setting Up AI Providers", + "description": "Install and configure AI providers for your tools", + "content": """ +

CmdForge is the brain, but AI providers are the muscle. Before your tools can do +anything smart, you need at least one provider configured. The good news? CmdForge has an +interactive installer that makes this painless.

+ +
+

What You'll Learn

+
    +
  • Using the interactive provider installer
    • +
  • Available provider options and their tradeoffs
    • +
  • Testing your provider setup
    • +
  • Managing multiple providers
    • +
+
+ +

The Interactive Installer

+ +

The easiest way to get started:

+ +
cmdforge providers install
+ +

You'll see a menu of available provider groups:

+ +
============================================================
+CmdForge Provider Installation Guide
+============================================================
+
+Available AI Provider Groups:
+
+  1. OpenCode
+     Cost: FREE tier available (4 models)
+     Models: opencode-pickle, opencode-deepseek, opencode-claude, ...
+
+  2. Claude (Anthropic)
+     Cost: Pay per token
+     Models: claude-haiku, claude-sonnet, claude-opus
+
+  3. Ollama (Local)
+     Cost: FREE (runs on your machine)
+     Models: ollama-llama, ollama-mistral, ollama-codellama
+
+  4. OpenAI
+     Cost: Pay per token
+     Models: openai-gpt4, openai-gpt35
+
+  0. Cancel
+
+Select a provider to install (1-4, or 0 to cancel):
+ +

Select a provider, and CmdForge will:

+
    +
  1. Show you the installation command
    2. +
  2. Offer to run it for you
    3. +
  3. Guide you through any post-install setup
    4. +
+ +

Choosing a Provider

+ +
+
+

Best for Getting Started: OpenCode

+
    +
  • 4 FREE models included
    • +
  • No API key required for free tier
    • +
  • One command install
    • +
  • Web UI for model management
    • +
+

Install: Option 1 in the installer

+
+
+

Best for Privacy: Ollama

+
    +
  • Runs 100% locally
    • +
  • No data leaves your machine
    • +
  • Free forever
    • +
  • Great for sensitive content
    • +
+

Install: Option 3 in the installer

+
+
+

Best Quality: Claude

+
    +
  • State-of-the-art reasoning
    • +
  • Long context windows
    • +
  • Excellent for complex tasks
    • +
  • Pay per use
    • +
+

Install: Option 2 in the installer

+
+
+

Most Flexible: OpenAI

+
    +
  • Wide ecosystem support
    • +
  • Fast response times
    • +
  • Reliable infrastructure
    • +
  • Pay per use
    • +
+

Install: Option 4 in the installer

+
+
+ +

Testing Your Setup

+ +

After installation, verify everything works:

+ +
# Test a specific provider
+cmdforge providers test opencode-pickle
+
+# The test sends a simple prompt and shows the response
+# You should see something like:
+# Testing provider: opencode-pickle
+# Sending test prompt...
+# ✓ Provider responded successfully!
+# Response: "Hello! I'm working correctly."
+ +

Viewing Configured Providers

+ +
# List all providers and their status
+cmdforge providers list
+ +

Output:

+ +
Configured providers:
+
+  NAME              COMMAND                     STATUS
+  opencode-pickle   opencode -m pickle          ✓ Available
+  claude-haiku      claude -m haiku -p          ✓ Available
+  ollama-llama      ollama run llama2           ✗ Not found
+  mock              echo '[MOCK]'               ✓ Available
+
+4 providers configured, 3 available
+ +

Manually Adding Providers

+ +

Need a custom provider? Add it manually:

+ +
# Add a new provider
+cmdforge providers add my-provider "my-ai-cli --prompt"
+
+# Add with description
+cmdforge providers add my-provider "my-ai-cli --prompt" --description "My custom AI"
+ +

Or edit ~/.cmdforge/providers.yaml directly:

+ +
providers:
+  - name: my-provider
+    command: "my-ai-cli --prompt"
+    description: "My custom AI provider"
+ +

Removing Providers

+ +
# Remove a provider you no longer use
+cmdforge providers remove old-provider
+ +

Using Multiple Providers

+ +

You can have many providers configured and choose per-tool or per-run:

+ +
# Use the tool's default provider
+cat file.txt | summarize
+
+# Override for this run
+cat file.txt | summarize --provider ollama-llama
+
+# Use a fast provider for quick tasks
+cat file.txt | summarize --provider opencode-pickle
+
+# Use a powerful provider for complex tasks
+cat file.txt | summarize --provider claude-opus
+ +

The Mock Provider

+ +

CmdForge includes a built-in mock provider for testing without API calls:

+ +
# Test your tool without using real AI
+cat file.txt | summarize --provider mock
+ +

This returns a placeholder response, perfect for:

+ + +

Next Steps

+ + +""", + "headings": [ + ("interactive-install", "The Interactive Installer"), + ("provider-options", "Choosing a Provider"), + ("testing", "Testing Your Setup"), + ("listing", "Viewing Configured Providers"), + ("manual-add", "Manually Adding Providers"), + ("removing", "Removing Providers"), + ("multiple", "Using Multiple Providers"), + ("mock", "The Mock Provider"), + ("next", "Next Steps"), + ], + }, + + "cli-reference": { + "title": "CLI Reference", + "description": "Complete reference for all CmdForge commands", + "content": """ +

A quick reference for every CmdForge command. Bookmark this page—you'll come back to it.

+ +

Tool Commands

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandDescription
cmdforgeLaunch the Visual Builder (desktop GUI)
cmdforge listList all installed tools
cmdforge createCreate a new tool (interactive wizard)
cmdforge edit <tool>Open tool config in your editor
cmdforge delete <tool>Remove a tool
cmdforge test <tool>Test a tool with mock provider
cmdforge run <tool>Run a tool directly (without wrapper)
cmdforge refreshRegenerate all wrapper scripts
cmdforge docs <tool>View or edit tool documentation
cmdforge check <tool>Check if tool dependencies are installed
+ +

Registry Commands

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandDescription
cmdforge registry search <query>Search for tools
cmdforge registry install <tool>Install a tool from registry
cmdforge registry uninstall <tool>Uninstall a registry tool
cmdforge registry info <tool>Show tool details
cmdforge registry publish <tool>Publish a tool to registry
cmdforge registry my-toolsList your published tools
cmdforge registry browseBrowse registry (interactive TUI)
+ +

Collection Commands

+ + + + + + + + + + + + + + + + + + + + + + +
CommandDescription
cmdforge collections listList available collections
cmdforge collections info <name>Show collection details
cmdforge collections install <name>Install all tools in collection
+ +

Provider Commands

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandDescription
cmdforge providers installInteractive provider installation guide
cmdforge providers listList configured providers
cmdforge providers checkCheck which providers are available
cmdforge providers add <name> <cmd>Add a new provider
cmdforge providers remove <name>Remove a provider
cmdforge providers test <name>Test a provider
+ +

Project Commands

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandDescription
cmdforge initCreate cmdforge.yaml manifest
cmdforge add <tool>Add tool to project dependencies
cmdforge installInstall project dependencies
cmdforge depsShow project dependencies
+ +

Config Commands

+ + + + + + + + + + + + + + + + + + + + + + +
CommandDescription
cmdforge config showShow current configuration
cmdforge config set <key> <value>Set a configuration value
cmdforge config connect <username>Connect to registry account
+ +

Useful Global Flags

+ + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
--helpShow help for any command
--versionShow CmdForge version
--provider <name>Override provider for tool execution
+ +

Important File Locations

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PathContents
~/.cmdforge/Tool configs directory
~/.cmdforge/<tool>/config.yamlIndividual tool configuration
~/.cmdforge/providers.yamlProvider configurations
~/.local/bin/Tool wrapper scripts
./cmdforge.yamlProject dependency manifest
+""", + "headings": [ + ("tool-commands", "Tool Commands"), + ("registry-commands", "Registry Commands"), + ("collection-commands", "Collection Commands"), + ("provider-commands", "Provider Commands"), + ("project-commands", "Project Commands"), + ("config-commands", "Config Commands"), + ("useful-flags", "Useful Global Flags"), + ("file-locations", "Important File Locations"), + ], + }, } @@ -3250,16 +4167,22 @@ def get_toc(): SimpleNamespace(slug="visual-builder", title="Visual Builder"), SimpleNamespace(slug="yaml-config", title="YAML Config"), ]), - SimpleNamespace(slug="registry-usage", title="Using the Registry", children=[]), + SimpleNamespace(slug="registry-usage", title="Using the Registry", children=[ + SimpleNamespace(slug="collections", title="Tool Collections"), + ]), SimpleNamespace(slug="arguments", title="Custom Arguments", children=[]), SimpleNamespace(slug="multi-step", title="Multi-Step Workflows", children=[ SimpleNamespace(slug="code-steps", title="Code Steps"), SimpleNamespace(slug="tool-steps", title="Tools Within Tools"), ]), SimpleNamespace(slug="testing-steps", title="Testing Sandbox", children=[]), - SimpleNamespace(slug="providers", title="Providers", children=[]), + SimpleNamespace(slug="providers", title="Providers", children=[ + SimpleNamespace(slug="provider-setup", title="Provider Setup"), + ]), + SimpleNamespace(slug="project-deps", title="Project Dependencies", children=[]), SimpleNamespace(slug="publishing", title="Publishing", children=[]), SimpleNamespace(slug="advanced-workflows", title="Advanced Workflows", children=[ SimpleNamespace(slug="parallel-orchestration", title="Parallel Orchestration"), ]), + SimpleNamespace(slug="cli-reference", title="CLI Reference", children=[]), ]