Skip to content

Project Dependencies

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:

  • "It works on my machine" - but not your teammate's
  • Tool updates break your workflow unexpectedly
  • Setting up a new machine means remembering every tool
  • CI/CD environments are a mystery

With cmdforge.yaml:

  • Everyone gets the same tools at the same versions
  • New team members run one command and they're ready
  • CI/CD setup is just cmdforge install
  • You control when to upgrade

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:

Constraint Meaning Example Matches
* Any version (latest) 1.0.0, 2.0.0, 3.5.2
1.2.3 Exact version only 1.2.3
^1.2.0 Compatible (same major) 1.2.0, 1.3.0, 1.9.9
~1.2.0 Approximate (same minor) 1.2.0, 1.2.1, 1.2.9
>=1.0.0 At least this version 1.0.0, 1.5.0, 2.0.0
<2.0.0 Before this version 1.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:

  • New team members getting set up
  • CI/CD pipeline preparation
  • Refreshing your environment after pulling changes

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:

  • Development - Use local/free models to save money
  • CI/CD - Use mock providers for testing
  • Production - Use high-quality cloud providers

Manifest Location

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

  • Per-project manifests - In each project root
  • Shared manifests - In a parent directory for multiple projects

Recommended Workflow

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

Next Steps

Edit this page on GitHub