Skip to content

Providers: One Tool, Many Engines

A CmdForge tool describes the work. A provider supplies the intelligence. Keeping those decisions separate means the same carefully tested tool can run on a private Ollama model, a coding CLI already installed on your machine, or an OpenAI-compatible API—without rewriting the workflow around an SDK.

A practical abstraction, not a lowest common denominator

CmdForge supports subprocess, API, and interactive PTY providers. A provider can also declare capabilities, locality, cost, latency, model identity, privacy policy, fallbacks, skills, and which nested tools it may use.

Begin with Discovery

On first run, CmdForge looks for supported AI CLIs on PATH, configured API-key environment variables, and locally installed Ollama models. You can repeat that inventory whenever your machine changes:

cmdforge providers discover
cmdforge providers discover --add
cmdforge providers list
cmdforge providers check

Discovery is a proposal until you add the results. Existing installations remain yours: the configuration is readable YAML at ~/.cmdforge/providers.yaml.

Three Ways to Reach a Model

Subprocess

Pipe prompts to CLIs such as Ollama, Codex, Claude Code, OpenCode, or Crush.

API

Call OpenAI-compatible endpoints with a model and an API-key environment variable.

PTY

Drive interactive command-line programs through a controlled terminal session.

Add a Provider Without Guesswork

# A private model running on this computer
cmdforge providers add studio-llama "ollama run llama3.2"   --type subprocess --model llama3.2 --locality local   --capability text --capability structured-json   --cost-class free --latency-class fast --data-policy private

# An OpenAI-compatible remote API; the secret stays in the environment
cmdforge providers add research-api https://example.net/v1   --type api --model research-model   --api-key-env RESEARCH_API_KEY --locality remote   --capability text --capability reasoning --data-policy public

Use cmdforge providers test NAME before building a workflow around a new provider. The CLI writes a versioned configuration and restricts its file permissions.

Select at the Right Layer

steps:
  - type: prompt
    provider: studio-llama
    prompt: "Extract the decisions from {input}"
    output_var: decisions

A step can name its usual provider, and cmdforge run TOOL --provider NAME can override it for a particular execution. This makes local development, CI testing, and higher-quality production runs variations of the same tool—not separate code paths.

Fallbacks Are Explicit Routes

Providers may name a fallback or a complete fallback chain. CmdForge traverses the chain with cycle detection and records every attempted provider. Presets such as free, fast, reasoning, and balanced are convenient starting points, but they are never a substitute for a privacy decision.

cmdforge providers add primary "model-cli --quiet"   --fallback-chain "primary,studio-llama,mock"

# Sensitive work should fail closed rather than cross a trust boundary
cmdforge run summarize-private --no-fallback --require-local   --data-classification private --result-envelope json

Facts and policy are different things

The provider records facts such as locality, capabilities, model identity, and maximum approved data classification. The caller decides what a particular job requires. Continue with Privacy and Routing Policy for strict execution and provenance.

Go Further

Edit this page on GitHub